Local code intelligence and persistent project memory for Codex and Claude Code. Explore TypeScript, JavaScript and Prisma through symbols, call chains and model relationships.
Quick start · Documentation · Releases · Roadmap · Contribute
A function name is only the beginning. Safe changes also require knowing who calls it, which models it touches, and which project decisions should survive the next AI session.
CodeMemory builds a local, queryable graph for a project you explicitly select. Your agent can follow relationships, retrieve focused source context and recall decisions you asked it to save. One shared installation serves your registered projects; each MCP connection stays bound to its own project.
Current release: 0.1.0-alpha.31. Available for early adopters on Windows, macOS and Linux. The release pipeline tests all three platforms; sustained large-repository and production acceptance remain open gates.
| Your task | How CodeMemory helps |
|---|---|
| Understand an unfamiliar repository | Find declarations, read file outlines and inspect focused source context. |
| Plan a refactor | Follow callers, callees, references and dependency paths before editing shared code. |
| Trace Prisma usage | Move from a schema model to statically resolved queries, their files, call lines and operation names. |
| Review dead code and duplication | Find bounded candidates for source review, with explicit analysis limits. |
| Keep architectural decisions | Store requested notes, conventions and decisions in persistent, project-scoped memory. |
| Check whether evidence is current | Inspect index generation, progress, exclusions, diagnostics and unresolved references. |
Try prompts like these after connecting your agent:
“Find the callers of
calculateTotaland show the source before suggesting a refactor.”“Where is the Prisma
Usermodel queried? Include operation names and file locations.”“Find duplicate-code candidates in this module and check whether their behavior is actually equivalent.”
“Remember this project decision: refunds must preserve a link to the original order.”
The agent decides when to invoke MCP tools. The installer adds project instructions to guide discovery and verification.
The opt-in memory workflow lets your coding agent submit selected conversation
evidence through MCP. Spark extracts English candidates; Haiku checks their
claims against exact quotes. You review candidates before they become active
project rules. The next task retrieves relevant rules with recall_context.
# Run in the selected project after updating and signing in to Codex and Claude CLIs.
codememory memory configure --enable --yes
codememory memory status
codememory memory candidatesYour MCP connection runs the queue in the background. Use codememory memory worker when no coding client is connected. This is a review workflow, not
unlimited inference or automatic truth: setup, approval and limits.
- Local analysis. Parsing and graph queries run locally. The optional memory workflow sends only explicitly submitted excerpts to your authenticated Spark/Haiku CLIs after per-project opt-in. It never reads chat history automatically. Your AI providers' data handling applies to those excerpts and any source your coding client requests.
- Explicit project boundaries. Register the directories you want. The server does not discover and index every repository on your machine.
- Relationships alongside source. Query symbols and dependencies, then inspect the exact code behind a finding.
- Visible limits. Diagnostics, unresolved references, pagination and source-preview bounds help distinguish evidence from assumptions.
- One shared runtime. Install once, register projects as needed, and update the active runtime across existing enabled registrations.
- MIT licensed. Inspect the implementation, contribute regressions, or adapt it to your workflow.
Open a terminal in the project you want to index. Install Bun 1.3.3+ and Git first. The bootstrap prepares the shared CLI, Docker and a dedicated PostgreSQL service. Docker permissions, first-run setup or a Windows reboot can require interaction. Releases currently require Bun and workspace dependencies; they are not standalone binaries.
Choose codex, claude or both. The examples below configure both clients. Omit --write / -Write to preview the selected-project installation.
curl -fsSL https://raw.githubusercontent.com/iOwsla/integra-codebase-memory/v0.1.0-alpha.31/bootstrap.sh | sh -s -- --project "$PWD" --client both --write
export PATH="${XDG_DATA_HOME:-$HOME/.local/share}/integra-code-memory/cli/bin:$PATH"Add the printed CLI directory to your shell profile to retain it in future terminals.
$installer = (Invoke-WebRequest -UseBasicParsing 'https://raw.githubusercontent.com/iOwsla/integra-codebase-memory/v0.1.0-alpha.31/bootstrap.ps1').Content
& ([scriptblock]::Create($installer)) -Project (Get-Location).Path -Client both -WriteInstallation and updates repair the persistent user PATH automatically. The PowerShell installer also refreshes its invoking session. After a CLI update, restart existing terminal windows or the IDE hosting them.
- Open the selected project in Codex or Claude Code and reload/approve its MCP connection if prompted.
- Ask the agent to run
codebase_statusand verify the selected root. Automatic indexing starts when the connection opens. - Wait for a published index and review diagnostics before relying on results. In a terminal,
codememory status --watchfollows progress.
The managed index database listens on 127.0.0.1:55433. To use an already prepared external index database, add --skip-services / -SkipServices and retain your DATABASE_URL. Use a dedicated index database, not your application's production database.
If setup requests a Windows reboot, return to the project directory afterward:
codememory system status
codememory system setup --project (Get-Location).PathPlatform installation and recovery · Codex setup · Claude Code setup
Run project commands from the directory you want to select; no path argument is required:
codememory projects add --client both
codememory index
codememory status --watch
codememory projects listindex shows live stages, sampled filenames and elapsed time on stderr, while its final stdout remains JSON. Use index --no-progress for quiet operation or status --watch --json for status events.
Use projects add --no-index if services are not ready, or --external-db for an external index database. Selecting a child directory keeps that exact scope; it does not silently expand to the parent Git root.
To disable a registration, close its active MCP sessions and run codememory projects remove --yes in that project. Source, index and memory are retained. See the CLI guide for service recovery and separate data-purge operations.
codememory updates # Check for a published release
codememory update # Install it into the shared runtimeOn Windows, codememory.cmd is also available. If an older PATH entry prevents command discovery:
& "$env:LOCALAPPDATA\integra-code-memory\cli\bin\codememory.cmd" update --version v0.1.0-alpha.31The updater validates the release, preflights enabled registrations, backs up changed settings and stops verified CodeMemory processes before switching the shared runtime. Project scopes and index data are preserved. Reconnect open MCP clients afterward. Update checks do not install releases in the background; set CODEMEMORY_UPDATE_CHECK=0 to disable checks.
Using alpha.16 or older? Follow the one-time migration guide. Keep the selected project's existing client and database mode.
CodeMemory indexes models, fields, enums, relations and foreign-key relationships alongside JS/TS sources. Query resolution follows the client and model delegate through supported static bindings; it does not depend on a variable being named prisma.
import { PrismaClient as Engine } from '@prisma/client';
const database = new Engine();
const user = database.user;
export function loadUsers() {
return user.findMany({ where: { active: true } });
}Search for User with search_symbols using kinds: ["MODEL"], then pass the selected model ID to find_references. Results can identify loadUsers, its file, call line and findMany operation. Multiple schemas remain distinct: select the correct model ID.
Arbitrary runtime factories, client extensions and raw SQL are not fully resolved. See the Prisma support matrix and examples.
flowchart LR
P[Selected project<br/>JS · TS · Prisma] --> S[Scoped scanner]
S --> A[Static analysis]
A --> G[(Local PostgreSQL<br/>Code graph + requested memory)]
G <--> M[Project-bound MCP server]
M <--> C[Codex / Claude Code]
CLI[Management CLI] --> S
The scanner respects .gitignore, a root .codememoryignore, configured exclusions, size limits and nested repository boundaries. Symlinks and temporary .workflow-tmp directories are excluded. The parser reads the scanner's permitted source set; completed graph publication is transactional.
Unchanged projects reuse their index. Source changes currently trigger conservative semantic re-analysis of the selected project. Session-owned watchers reconcile changes and shut down with their MCP process. There is no global indexing daemon.
| Purpose | Tools |
|---|---|
| Status and discovery | codebase_status, search_symbols, search_code |
| Source context | get_symbol, get_file_outline, get_file_context |
| Relationships | find_references, find_callers, find_callees, trace_dependencies |
| Quality review | find_dead_code_candidates, find_duplicate_code |
| Explicit memory | remember, search_memory |
Architecture · Project isolation · MCP protocol · Project memory
JavaScript, TypeScript and Prisma are supported within the documented static analysis scope. Kotlin and other language adapters are not implemented. Dynamic dispatch and external dependencies can remain unresolved.
READY means a graph is available, not that all relationships are known. Inspect incompleteReasons, diagnostics, exclusions and unresolved references. Follow pagination; a truncated preview is not a whole function. A symbol with no recorded callers is a review candidate, not proof that it can be deleted.
Use a root .codememoryignore to exclude project-specific scratch outputs without changing Git tracking. See the layered ignore policy.
Large repositories can require more parser time and memory. See indexing configuration, analysis limitations and verification evidence. No production throughput or memory guarantee is claimed.
Start with the documentation hub, or go directly to:
- Installation, updates and troubleshooting
- Prisma schema and model usage
- Dead-code and duplication reports
- Parser coverage and index configuration
- Roadmap and release acceptance
- Changelog and GitHub releases
Useful contributions include small reproductions for missed relationships, platform installation feedback, documentation improvements and parser regressions. Read CONTRIBUTING.md for setup and review expectations.
Report a bug · Request a feature
If CodeMemory helps your workflow, star the repository and share a reproducible, redacted example of what works or what needs improvement. Real usage feedback helps set priorities. For vulnerabilities, follow SECURITY.md.
MIT — Copyright © 2026 CodeMemory contributors.
Register each project once. The installer enables session project attachment for
Codex and Claude Code and installs the instructions that let the agent handle it.
The agent calls list_projects; registered roots reported by the client are
attached automatically. For another project the user opened in the conversation,
the agent can call attach_project without editing MCP configuration.
Queries and memory writes use the returned projectScopeId as project.
Only attached projects are accessible; this does not index every registered
project. Existing installations need an installer upgrade and MCP reconnect.
See session project attachment
for client limitations and lifecycle details.
For manual fixed scopes, repeat --project:
codememory mcp --project /absolute/project-x --project /absolute/project-y --auto-index --watchAttach project-relative implementation, Prisma model and test paths to an active
memory with create_memory_checkpoint or codememory memory checkpoint.
Recall checks recorded file hashes and flags changed or missing evidence while
preserving the original decision. Reported test results are not independent test
certification. See checkpoint usage and limits.
Alpha.29 adds opt-in Markdown evidence, actual Git file changes (including fx commits), staged/unstaged observations and reviewed document rules. It shares PostgreSQL and stays isolated to the selected project. Collection and model processing require separate project-level opt-ins.
See setup, commands, scope, budgets and backups and the implementation plan.
An opt-in shared HTTP provider layer adds DeepSeek, per-project routing, OS-managed credentials and local usage allowances. Available starting with alpha.30. See API provider setup and limits.
Default help shows everyday commands. Use codememory --help-all for the complete
command list, or codememory history --help-all for evidence review, recovery and
maintenance. codememory providers add --help-all shows advanced API limits and
rates. Explicit commands and existing scripts retain their behavior.