CodeWell

CodeWell gives AI coding agents long-term memory.
Index once. Search, trace, and recall across every session — without calling a single LLM API.

CodeWell 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.

Installation

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.

Quick Start

# 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

Getting Started with Your AI Agent

CodeWell is most useful when connected to an AI coding agent via MCP. Here's the complete flow:

1. Index Your Project

cd my-project
codewell index .

This creates a .codewell/codewell.sqlite3 database. Do this once per project.

2. Connect Your Agent (One Command)

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"]
      }
    }
  }
}

3. Let Your Agent Use It

Restart your agent. It will automatically discover these MCP tools:

Tool	What it does
get_context_pack	Get structured code context for a query
search_code	Search indexed code with FTS5
trace_symbol	Trace symbol definitions and call edges
get_database_status	Check index status and coverage
search_revision_memory	Search past fixes and adaptations

The agent will call get_context_pack before editing code — no manual prompting needed.

4. That's It

After the initial codewell index ., everything else is automatic. The agent decides when to retrieve context, and CodeWell provides it.

Status

CodeWell is V2 beta (v2.0.0-beta). The current release supports:

• local workspace indexing for Python, TypeScript, and JavaScript source files
• public GitHub repository indexing by URL
• SQLite FTS5 lexical code search
• symbol tracing over indexed call edges
• ambiguity-aware retrieval with subgoal decomposition, workspace clustering, and primary/backup branch selection (V2)
• JSON context pack generation with graph-aware file expansion
• optional workspace-local document attachments and manual code-to-doc links
• revision memory for failed snippet adaptations and fixed variants
• a thin MCP server over the same local engine

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 Evaluation

V2 has been validated on 17 tasks across 12 domains, 5 codebases, and 2 languages (TypeScript + Python). Median results (3×3 repeated-run protocol):

Metric	Result
Elapsed time	88% tasks net-positive
Tool calls	100% tasks net-positive
Token usage	94% tasks net-positive

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.

Quickstart

Install for Development

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.

Verify an Installed CLI

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.

Run the Demo

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.

Smoke Test a Local Project

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.

Run the Fixture Evaluation

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:

• Python login fixture
• TypeScript login fixture
• TypeScript barrel and re-export fixture
• TypeScript extended syntax fixture for object methods, namespaces, and decorators
• TypeScript arrow fixture for class-field methods and object-property arrow functions
• TypeScript route-entry fixture for app.ts -> routes.ts -> service.ts expansion
• TypeScript command-entry fixture for cli.ts -> service.ts command context expansion
• TypeScript test-entry fixture for tests/service.spec.ts -> src/service.ts test context expansion
• TypeScript named re-export fixture for export { x as y } from ... multi-hop chains
• TypeScript class-call fixture coverage for this. and super. relationships through trace
• TypeScript context coverage for alias imports, multi-hop barrel/re-export expansion, and router-entry, command-entry, and test-entry relationships

To 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:

• the navigation-heavy bucket is the strongest positive bucket
• the obvious-near-obvious bucket remains a clear boundary where retrieval overhead can dominate
• strong_multi_goal tasks now use a full 3-pair repeated-run protocol before they are read as wins or losses

CLI Usage

Index a Local Project

codewell 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.

Raw Source Safety

CodeWell is designed so your original code can remain a read-only input.

In detached-library mode:

• CodeWell reads raw workspaces, GitHub snapshots, and local ZIP files as source inputs.
• CodeWell writes derived artifacts under the configured library root, not into the raw source.
• The original ZIP file is not modified.
• Revision memory and repair audit records are stored as separate derived records.

Under a library root, the main directories are:

• workspaces/: detached manifests and derived workspace databases
• github/: downloaded GitHub archive cache
• archives/: extracted local ZIP cache
• diagnostics/: reserved space for future diagnostics and operational artifacts

Replaceable derived artifacts:

• SQLite indexes
• extracted archive and GitHub cache snapshots
• manifests that can be rebuilt by reindexing

Durable memory artifacts:

• revision memory about failed reuse and verified fixes
• repair audit logs describing maintenance actions

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.

Search Indexed Code

codewell search login --db tests/fixtures/python_basic/.codewell/codewell.sqlite3

Search uses SQLite FTS5 over paths, symbols, and source content.

Trace a Symbol

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.

Inspect a Database

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.

Build a Context Pack

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.

Attach Local Papers and Notes

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:

• Attached documents are not full-text indexed yet.
• README.md, Markdown notes, and PDFs are not part of search, trace, or the core lexical retrieval path.
• A document only shows up in 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.
• Attached document references are intentionally capped and prioritized for agents: symbol-linked docs come before file-linked docs, which come before opt-in project docs.

Record Revision Memory

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.

Index a Public GitHub Repository

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.

Index a Local ZIP Archive

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:

• check that the path exists and ends with .zip
• verify that the ZIP can be opened normally
• rebuild the archive if it is empty, only contains empty directories, or contains unsafe paths such as absolute paths or ..
• retry with --library-root if you want extracted cache data separated from other work
• rerun codewell index ... after fixing the archive; the raw ZIP itself is never modified

If the archive opens but CodeWell indexes 0 supported source files:

• check whether the archive only contains docs, binaries, vendored assets, or unsupported languages
• supported source suffixes are .py, .ts, .tsx, .js, .jsx, .mjs, and .cjs
• inspect recent ingest runs with:

codewell 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

Run the MCP Server

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_workspace
• search_code
• trace_symbol
• get_context_pack
• get_database_status
• record_failure
• record_revision
• search_revision_memory

Stable example payloads for CLI JSON commands and MCP tools are in docs/JSON_EXAMPLES.md.

Run the Local UI

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.
• Failed ingest runs expose both an inspect command and a suggested command so recovery steps can be copied without switching back to the terminal.

Why This Exists

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:

1. Index a local project or public GitHub repository.
2. Build a lightweight code graph from files, symbols, imports, calls, tests, and routes.
3. Retrieve a compact context pack for the current coding task.
4. Record which snippets worked, which failed, how they were fixed, and how the fix was verified.
5. Reuse verified revisions in future projects without polluting the original source.

Memory Layers

CodeWell combines three memory layers:

• Project Graph: the user's current local project, indexed from source files.
• Reference Graph: external repositories or snippets, stored with provenance metadata.
• Revision Graph: bug reports, failed adaptations, patches, explanations, test results, and verified fixed versions.

Verification Model

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.

Non-Goals

• CodeWell should not replace Claude Code, Codex, Cursor, Continue, or Aider.
• CodeWell should not automatically copy random internet code into a project.
• CodeWell should not call LLMs during the default indexing path.
• CodeWell should not treat unverified snippets as trusted fixes.

Roadmap

• finish the Raw / Derived / Manifest library model and make detached-library workflows easier to inspect and query
• add a unified import layer for local folders, GitHub repositories, and local ZIP archives
• deepen TS/JS parsing beyond the current heuristic baseline
• convert recent TS/JS fixture wins into task-level evaluation coverage
• validate retrieval on more real JS/TS tasks and repositories
• deepen the local UI beyond the current read-only ops console and search/revision views
• harden private GitHub support beyond the current token-auth archive path
• add richer graph queries beyond direct symbol tracing
• add optional local embeddings and reranking
• add UI exploration for repositories, snippets, revisions, sources, and evidence

Research Direction

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.