CodeWell
CodeWell gives AI coding agents long-term memory.
Index once. Search, trace, and recall across every session — without calling a single LLM API.
Potencialize seu agente
Instalação do publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
Ainda não há uma versão empacotada no registro. Siga o README do repositório.
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirCodeWell is a lightweight local memory layer for AI coding tools such as Claude Code, Codex, Cursor, Continue, and Aider. It indexes code into SQLite, retrieves compact context packs, and records verified snippet revisions so agents do not repeat the same debugging work across sessions.
CodeWell is not a coding agent. It is a local context and memory engine that agents can call through a CLI or an MCP server.
In practice, MCP is the main integration surface for coding agents. The CLI is primarily a local bootstrap, audit, and correction interface for humans.
pip install codewell
Or from source:
git clone https://github.com/Fitz798/CodeWell.git
cd codewell
pip install -e .
Requires Python 3.10+. The only runtime dependency is mcp>=1.0.
# Index a local project
codewell index ./my-project
# Search for code
codewell search "auth middleware"
# Get a context pack for an agent
codewell context "fix auth middleware wiring" --token-budget 4096
# Start the MCP server
codewell serve --mcp
CodeWell is most useful when connected to an AI coding agent via MCP. Here's the complete flow:
cd my-project
codewell index .
This creates a .codewell/codewell.sqlite3 database. Do this once per project.
codewell setup
This creates .mcp.json in your project root and indexes your code. That's it.
Or manually add CodeWell to your agent's MCP configuration:
Claude Code (~/.claude/claude_desktop_config.json or project .mcp.json):
{
"mcpServers": {
"codewell": {
"command": "codewell",
"args": ["serve", "--mcp"]
}
}
}
Cursor (.cursor/mcp.json in your project root):
{
"mcpServers": {
"codewell": {
"command": "codewell",
"args": ["serve", "--mcp"]
}
}
}
Continue (~/.continue/config.json):
{
"experimental": {
"mcpServers": {
"codewell": {
"command": "codewell",
"args": ["serve", "--mcp"]
}
}
}
}
Restart your agent. It will automatically discover these MCP tools:
The agent will call get_context_pack before editing code — no manual prompting needed.
After the initial codewell index ., everything else is automatic. The agent
decides when to retrieve context, and CodeWell provides it.
CodeWell is V2 beta (v2.0.0-beta). The current release supports:
The default path is local-first. No LLM API, vector database, hosted service, GPU, or background daemon is required — including the V2 multi-goal retrieval path.
V2 has been validated on 17 tasks across 12 domains, 5 codebases, and 2 languages (TypeScript + Python). Median results (3×3 repeated-run protocol):
See docs/V2_MASTER_PLAN.md for the full roadmap and docs/V2_PROGRESS_2026-05-23.md for the detailed progress log. docs/AGENT_EVALUATION.md for the current internal A/B protocol and boundary read.
git clone https://github.com/Fitz798/CodeWell.git
cd CodeWell
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
On Windows PowerShell:
git clone https://github.com/Fitz798/CodeWell.git
cd CodeWell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[dev]"
Run the checks:
python -m pytest
python -m ruff check .
python -m mypy
python -m pip check
Run the full pre-release gate:
python scripts/check_release.py
To check only the installable package path, build a wheel and smoke test the installed CLI:
python scripts/check_package.py
See CHANGELOG.md for the current unreleased feature set. For MVP scope, technical stack, and maintainer engineering protocol, see docs/PROJECT_GUIDE.md. For the current V1 evaluation boundary and product-facing evidence summary, see docs/V1_EVALUATION_NOTE.md. For the current V1 freeze-candidate scope and snapshot guidance, see docs/V1_FREEZE_CANDIDATE.md. For the next-phase architecture and improvement roadmap, see docs/ARCHITECTURE_V2.md. For the current V2 branch kickoff and first research slice, see docs/V2_KICKOFF.md. For the current prioritized execution plan after the recent library/admin work, see docs/IMPROVEMENT_PLAN.md. For the current launch decision and remaining release evidence, see docs/RELEASE_READINESS.md. For stable CLI and MCP output examples, see docs/JSON_EXAMPLES.md.
After installing CodeWell, this throwaway project checks the core loop in under five minutes: index, status, search, trace, context, record a revision, and recall it.
PowerShell:
New-Item -ItemType Directory -Force codewell-first-run | Out-Null
Set-Location codewell-first-run
@'
def login_user(name: str) -> bool:
return bool(name)
'@ | Set-Content -Encoding utf8 auth.py
@'
from auth import login_user
def handle_login(name: str) -> str:
if login_user(name):
return "ok"
return "denied"
'@ | Set-Content -Encoding utf8 app.py
codewell index .
codewell status
codewell search login
codewell trace login_user
codewell context "where is login handled?" --budget 800
codewell record-failure snippet-auth --target-project demo --error-log "ImportError: missing jwt"
codewell record-revision snippet-auth --failure-id 1 --fix-diff "Use pyjwt import." --explanation "The target project uses pyjwt." --state test_verified --test-command pytest --test-result "1 passed"
codewell revision-search pyjwt
Bash:
mkdir -p codewell-first-run
cd codewell-first-run
cat > auth.py <<'PY'
def login_user(name: str) -> bool:
return bool(name)
PY
cat > app.py <<'PY'
from auth import login_user
def handle_login(name: str) -> str:
if login_user(name):
return "ok"
return "denied"
PY
codewell index .
codewell status
codewell search login
codewell trace login_user
codewell context "where is login handled?" --budget 800
codewell record-failure snippet-auth --target-project demo --error-log "ImportError: missing jwt"
codewell record-revision snippet-auth --failure-id 1 --fix-diff "Use pyjwt import." --explanation "The target project uses pyjwt." --state test_verified --test-command pytest --test-result "1 passed"
codewell revision-search pyjwt
Expected signals: status shows one repository, search prints app.py and handle_login,
trace and context print JSON, and revision-search finds snippet-auth.
python scripts/demo.py
The demo copies the test fixture into a temporary directory, indexes it, searches for login,
traces login_user, builds a context pack, records a failed adaptation, records a verified
revision, and searches revision memory.
python scripts/smoke_real_project.py /path/to/python-project --query auth --query config
By default the smoke script copies the target project into a temporary directory, excluding common
cache/build folders, then runs index, status, search, and context. Pass --in-place only
when you want CodeWell to write .codewell into the original project.
python scripts/evaluate_fixture.py
The fixture evaluation prints a JSON report for the core usefulness loop: indexing, search, symbol tracing, context packing, and revision memory recall. See docs/EVALUATION.md for the real-project evaluation template and metrics.
To evaluate a local project against a JSON task list:
python scripts/evaluate_project.py /path/to/python-project tasks.json
The project evaluator reports pass/fail checks plus recall, precision, budget, and latency metrics so repeated runs can be compared.
Current bundled fixture and evaluation coverage includes:
app.ts -> routes.ts -> service.ts expansioncli.ts -> service.ts command context expansiontests/service.spec.ts -> src/service.ts test context expansionexport { x as y } from ... multi-hop chainsthis. and super. relationships through traceTo run the built-in CodeWell self-evaluation:
python scripts/evaluate_project.py . evaluations/codewell_self.json
python scripts/evaluate_project.py . evaluations/codewell_natural.json
python scripts/evaluate_project.py . evaluations/codewell_acceptance.json
For agent A/B testing with Claude Code or similar tools, use:
python scripts/agent_eval_session.py run-pair --task-id express_login_flow_patch_area --claude-model deepseek-v4-pro[1m]
That creates fresh workspace copies, runs both baseline and codewell in non-interactive
mode, saves the raw outputs, and records both results automatically. See
docs/AGENT_EVALUATION.md for the full workflow.
For evaluation hygiene, keep clean baseline repositories under
eval-repos/source-readonly/ and let the evaluation helper copy from there into
CodeWell_test/runs/.
Do not use eval-repos/github/ as a clean baseline source for formal A/B runs. Recent agent-eval
handoff findings showed task-related pollution in at least one copied repository there.
Current maintained internal evaluation read:
navigation-heavy bucket is the strongest positive bucketobvious-near-obvious bucket remains a clear boundary where retrieval overhead can dominatestrong_multi_goal tasks now use a full 3-pair repeated-run protocol before they are read as
wins or lossescodewell index tests/fixtures/python_basic
To bootstrap a detached library root before indexing anything:
codewell init-library ~/.codewell
This creates the recommended workspaces, github, archives, and diagnostics directories
without touching any raw source tree.
The same index entry point also accepts GitHub repository URLs and local ZIP archives.
CodeWell creates a local database at:
tests/fixtures/python_basic/.codewell/codewell.sqlite3
Index data is ignored by Git through .gitignore.
To keep the raw source tree untouched, use detached-library mode:
codewell index tests/fixtures/python_basic --library-root ~/.codewell
This stores the SQLite database and manifest under the external library root instead of writing
.codewell/ into the indexed project.
When you later run search, trace, context, status, revision-search, or serve --ui
from inside that same workspace, pass the same --library-root or set
CODEWELL_LIBRARY_ROOT, and CodeWell will auto-discover the matching detached database
through the workspace manifest.
CodeWell is designed so your original code can remain a read-only input.
In detached-library mode:
Under a library root, the main directories are:
workspaces/: detached manifests and derived workspace databasesgithub/: downloaded GitHub archive cachearchives/: extracted local ZIP cachediagnostics/: reserved space for future diagnostics and operational artifactsReplaceable derived artifacts:
Durable memory artifacts:
If you do want legacy in-place mode, CodeWell can still create .codewell/ inside a project.
Use detached-library mode when preserving a clean raw source tree matters.
codewell search login --db tests/fixtures/python_basic/.codewell/codewell.sqlite3
Search uses SQLite FTS5 over paths, symbols, and source content.
codewell trace login_user --db tests/fixtures/python_basic/.codewell/codewell.sqlite3
The output is JSON with matching symbol definitions, source excerpts near those definitions,
direct incoming callers, and direct outgoing calls from the indexed call graph.
Source excerpts are capped by default; pass --source-lines to tune the maximum per symbol or
--source-lines 0 to omit excerpts.
codewell status --db tests/fixtures/python_basic/.codewell/codewell.sqlite3
codewell overview --db tests/fixtures/python_basic/.codewell/codewell.sqlite3
The output summarizes schema version, repositories, indexed files, symbols, imports, call edges, parse errors, and revision memory counts.
codewell context "where is login handled?" \
--db tests/fixtures/python_basic/.codewell/codewell.sqlite3 \
--budget 800 \
--response-mode default
The output is JSON designed for an agent prompt or MCP tool result. It includes selected files,
symbols, snippets, imports, call edges, per-file selection reasons, budget-aware symbol traces,
agent-ready symbol neighborhoods, a concise agent_brief, and related revision memory within the
requested budget.
When the top lexical match depends on nearby support code, CodeWell may also add a small number
of related files discovered through imports, caller files, and callee definitions.
For Python projects, this expansion includes common static test, command, and route entrypoint
files when the query suggests those relationships.
For TypeScript and JavaScript projects, it also supports relative-import graph expansion and common
test, command, route, barrel-file, alias-import, re-export, and importer-entry relationships.
When a matched file has too much metadata, CodeWell truncates symbols/imports/call edges and
reports omitted counts in the file entry.
Context-pack control surface:
--response-mode compact|default|debug selects a preset for expansion density and diagnostics.--no-revisions skips revision-memory recall when only live code context is needed.--include-project-docs prefers manually linked project-level documents in the context pack.--symbol-trace-limit and --trace-related-limit control trace breadth.--symbol-neighborhood-limit and --neighbor-definition-limit control how much caller/callee
neighborhood structure is returned for agents.debug mode keeps the same core schema but returns richer diagnostics, including lexical ranking
signals, graph expansion counts, metadata truncation counts, and the stopping reason when assembly
ends early due to budget pressure.
CodeWell is still code-first. Documents are currently an optional attachment layer, not part of the main code index.
Recommended layout for documents you want to keep with one project:
your-project/
.codewell/
docs/
attached/
links.json
Recommended flow:
codewell attach-doc /path/to/paper.pdf --workspace /path/to/your-project --type paper --copy
codewell link-doc paper --workspace /path/to/your-project --source-type symbol --source-id login_user --relation explained_by --target-locator "sec-3"
codewell list-docs --workspace /path/to/your-project
What these commands do:
attach-doc registers a local file and, with --copy, copies it into
.codewell/docs/attached/.link-doc creates an explicit manual link from a project, file, or symbol to that
document.unlink-doc removes one manual link when a relation was added by mistake or needs to be updated.list-docs shows all attached documents, all manual links, and which documents are still
unlinked.Useful filters for list-docs:
--doc-id <id> narrows output to one document.--source-type project|file|symbol shows links, and the linked documents, for one source type.--linked-only shows only documents that currently have matching links.--unlinked-only shows only documents that still need linking.Current behavior and limits:
README.md, Markdown notes, and PDFs are not part of search, trace, or the core lexical
retrieval path.context after you manually link it with link-doc.context surfaces linked documents as lightweight references only. It does not parse or embed
the document body.codewell record-failure snippet-auth \
--target-project target-app \
--error-log "ImportError: missing jwt" \
--command pytest \
--file-ref auth.py \
--db .codewell/codewell.sqlite3
codewell record-revision snippet-auth \
--failure-id 1 \
--fix-diff "Replace jose import with pyjwt import." \
--explanation "The target project uses pyjwt instead of jose." \
--test-command pytest \
--test-result "1 passed" \
--state test_verified \
--applicability-notes "Projects using pyjwt." \
--db .codewell/codewell.sqlite3
codewell revision-search pyjwt --db .codewell/codewell.sqlite3
Original snippets are never overwritten. Adaptations are stored as separate revision records with failure evidence, fix notes, verification output, and applicability notes. CodeWell also normalizes revision-memory inputs and reuses an existing revision record when an identical fix payload is recorded again, so repeated runs do not create exact duplicate memory. Revision search also reports why a fix matched and warns when a result is stale, rejected, unverified, or missing applicability guidance.
codewell index https://github.com/owner/repo
Public GitHub ingest downloads an archive snapshot, caches it under .codewell/github, records
source URL/ref/commit/license metadata when available, and indexes the extracted supported source
files.
Detached-library mode also works for GitHub ingest:
codewell index https://github.com/owner/repo --library-root ~/.codewell
For private repositories, pass a token explicitly:
codewell index https://github.com/owner/private-repo --github-token YOUR_TOKEN
You can also set CODEWELL_GITHUB_TOKEN or GITHUB_TOKEN. Do not embed credentials in the URL;
CodeWell rejects credential-bearing GitHub URLs so tokens are not stored in database provenance.
codewell index /path/to/project.zip --library-root ~/.codewell
CodeWell extracts the archive into its managed cache, keeps the original ZIP untouched, and then
indexes the extracted supported source files as an archive source.
If archive ingest fails:
.zip..--library-root if you want extracted cache data separated from other workcodewell index ... after fixing the archive; the raw ZIP itself is never modifiedIf the archive opens but CodeWell indexes 0 supported source files:
.py, .ts, .tsx, .js, .jsx, .mjs, and .cjscodewell ingest-history --library-root ~/.codewell --limit 5
If a detached-library ingest run fails after extraction or during indexing, inspect the detailed stage history first:
codewell ingest-history --library-root ~/.codewell --run-id <run-id>
Then retry the same command after fixing the source issue:
codewell index /path/to/project.zip --library-root ~/.codewell
codewell serve --mcp
Example MCP client configuration after installing CodeWell:
{
"mcpServers": {
"codewell": {
"command": "codewell",
"args": ["serve", "--mcp"]
}
}
}
When running directly from a checkout, use:
{
"mcpServers": {
"codewell": {
"command": "python",
"args": ["-m", "codewell", "serve", "--mcp"],
"cwd": "/path/to/CodeWell"
}
}
}
Current MCP tools:
index_workspacesearch_codetrace_symbolget_context_packget_database_statusrecord_failurerecord_revisionsearch_revision_memoryStable example payloads for CLI JSON commands and MCP tools are in docs/JSON_EXAMPLES.md.
codewell serve --ui --db tests/fixtures/python_basic/.codewell/codewell.sqlite3
The local UI is read-only. It shows database status, indexed repositories, lexical code search, revision-memory search, recent ingest runs, detached workspace health, repair queue state, and repair-audit summaries, ingest stage details, plus source provenance and raw/derived boundary metadata, in a browser without requiring direct SQL access.
When started with --library-root, the UI also acts as a detached-library ops console:
Workspace Health shows per-workspace source kind, manifest/database state, and rebuild hints.Repair Queue shows a suggested command for the current repair action and lets you copy it
directly.Source Provenance and Raw / Derived Boundary make the immutable raw-input path explicit and
expose copy buttons for raw, derived, DB, and source paths.Onboarding Hints gives first-run commands for init-library, detached index, and reopening
the UI against the same library root.AI coding agents often lose important repository context between sessions. They may repeatedly search the same files, copy external snippets that need project-specific changes, and spend tokens debugging migration errors that were already solved before.
CodeWell focuses on a practical loop:
CodeWell combines three memory layers:
Each revision has a verification state:
unverified: saved without enough evidence.reported_fixed: the agent reported a fix, but no structured test evidence exists.metadata_verified: error logs, patch diff, and passing output are internally consistent.test_verified: CodeWell or the user reran a test command successfully.reproduced_verified: the failure was reproduced before the patch and passed after the patch.stale: the source or target project changed enough that the revision may no longer apply.rejected: the revision was found incorrect or unsafe.This prevents the memory store from silently polluting future retrieval.
The first goal is a useful local tool. Research evaluation can come after the MVP is working.
The strongest research question is:
Can local revision memory reduce repeated debugging work for AI coding agents across repository-level tasks?
Potential evaluation metrics include context recall, token usage, tool-call count, query latency, indexing time, repeated bug reduction, patch success rate, and human review effort.
Local coding memory for AI agents. MCP-native. No LLM API required.
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
CodeWell roda localmente via stdio.
Última verificação: 2026-10-28. Local coding memory for AI agents. MCP-native. No LLM API required.