{"_id":"@threedu/codebase-memory","_rev":"10-4236e76f463970d65eaff666460ef987","name":"@threedu/codebase-memory","dist-tags":{"latest":"0.5.0"},"versions":{"0.3.0":{"name":"@threedu/codebase-memory","version":"0.3.0","keywords":["mcp","model-context-protocol","ai-agents","code-index","codebase","claude-code","cursor"],"author":{"name":"Khang"},"license":"MIT","_id":"@threedu/codebase-memory@0.3.0","maintainers":[{"name":"threedu","email":"khang180424@gmail.com"}],"homepage":"https://github.com/ThreeDu/Codebase-Memory#readme","bugs":{"url":"https://github.com/ThreeDu/Codebase-Memory/issues"},"bin":{"codemem":"dist/src/cli.js"},"dist":{"shasum":"d51ff28511108cbde189924c66b42e17a74d165d","tarball":"https://registry.npmjs.org/@threedu/codebase-memory/-/codebase-memory-0.3.0.tgz","fileCount":13,"integrity":"sha512-tQ7RZpPHyCSCfip6GFMXTkTs1n7du3my1kBe0weIqRwmYjJ8C51tFQfV0VEBu7U9rOokd7PS9qQ060mguxJ/uw==","signatures":[{"sig":"MEUCIQDOkYpxXIMB5Q8x35gl3Z7FzZX3tLKE6WpTEgejdmyybwIgRJsuYxZx0ZFnfHLs0Whun9ceK8CCwkwz1W8qVtRNXYo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCPE2RQBgM+HYAlJwKYFYl54ffUsOt7dvk4LtOOfDhChwIgf94u6jNcYSfh2BBBfE4eDxZN8d6bhitJKfq1q5OmX/k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":147069},"type":"module","engines":{"node":">=20"},"gitHead":"51c5457f009d5028332f7bd95b6555c6df26e3a7","scripts":{"test":"npm run build && node --test dist/test/*.test.js","build":"tsc","prepare":"npm run build","prepublishOnly":"npm test"},"_npmUser":{"name":"threedu","email":"khang180424@gmail.com"},"repository":{"url":"git+https://github.com/ThreeDu/Codebase-Memory.git","type":"git"},"_npmVersion":"11.6.2","description":"Long-term codebase memory for AI coding agents: module map, entry points, and notes, served over CLI and MCP.","directories":{},"_nodeVersion":"24.11.1","dependencies":{"zod":"^4.6.7","typescript":"~5.9","@modelcontextprotocol/sdk":"^1.32.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"^26.6.6"},"_npmOperationalInternal":{"tmp":"tmp/codebase-memory_0.3.0_1793543651380_0.7348818420092311","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@threedu/codebase-memory","version":"0.4.0","keywords":["mcp","model-context-protocol","ai-agents","code-index","codebase","claude-code","cursor"],"author":{"name":"Khang"},"license":"MIT","_id":"@threedu/codebase-memory@0.4.0","maintainers":[{"name":"threedu","email":"khang180424@gmail.com"}],"homepage":"https://github.com/ThreeDu/Codebase-Memory#readme","bugs":{"url":"https://github.com/ThreeDu/Codebase-Memory/issues"},"bin":{"codemem":"dist/src/cli.js"},"dist":{"shasum":"4fca623247c63c03a166c8ec985435f955c72c35","tarball":"https://registry.npmjs.org/@threedu/codebase-memory/-/codebase-memory-0.4.0.tgz","fileCount":13,"integrity":"sha512-HEvPZS1+dC2HZ/a+6R8Odhw5nuxkuIVpCpZFyNNnK8FRlax1p+kJ309EqAMIRG5Q3PMAVzu0BrGBj/WCjgjTyQ==","signatures":[{"sig":"MEQCIFFf5ebGTH4geaW9GsGMcetkMkxtguXM8RBck2UDBs8PAiB5bltKE8FQFrn5V6D2gyyKuIOlUkb04hYRhZLezf7w2Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQDBAL7F+ba7d3402gXBjUl2zB0HMegq/fxwNIVB0l88mAIgZjxIQfjw2NRqBv2iGqvj6nK1k2SA1kt2ctomJsCFSqw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":176077},"type":"module","engines":{"node":">=20"},"gitHead":"64ff2d87160ddb6bdb329408bc7f63326bf34367","scripts":{"test":"npm run build && node --test dist/test/codemem.test.js dist/test/interfaces.test.js","build":"tsc","prepare":"npm run build","prepublishOnly":"npm test"},"_npmUser":{"name":"threedu","email":"khang180424@gmail.com"},"repository":{"url":"git+https://github.com/ThreeDu/Codebase-Memory.git","type":"git"},"_npmVersion":"11.6.2","description":"Long-term codebase memory for AI coding agents: module map, entry points, and notes, served over CLI and MCP.","directories":{},"_nodeVersion":"24.11.1","dependencies":{"zod":"^4.6.7","typescript":"~5.9","@modelcontextprotocol/sdk":"^1.32.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"^26.6.6"},"_npmOperationalInternal":{"tmp":"tmp/codebase-memory_0.4.0_1793698721302_0.3083641281216253","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@threedu/codebase-memory","version":"0.4.1","keywords":["mcp","model-context-protocol","ai-agents","code-index","codebase","claude-code","cursor"],"author":{"name":"Khang"},"license":"MIT","_id":"@threedu/codebase-memory@0.4.1","maintainers":[{"name":"threedu","email":"khang180424@gmail.com"}],"homepage":"https://github.com/ThreeDu/Codebase-Memory#readme","bugs":{"url":"https://github.com/ThreeDu/Codebase-Memory/issues"},"bin":{"codemem":"dist/src/cli.js"},"dist":{"shasum":"8cb88092551d4345ad2f98c02122a276d2c26d11","tarball":"https://registry.npmjs.org/@threedu/codebase-memory/-/codebase-memory-0.4.1.tgz","fileCount":13,"integrity":"sha512-a9gZ5+aBiwIlJJGhgmnak3ynU53n92HCRa4uZzpK7svBZeOG6UFhU9JV7gI5AJkuooGjmW1GCqbsHHOrqz/Mlg==","signatures":[{"sig":"MEYCIQCi/lxS56b1ATDyeocyiHFKwUaVKYfX++lYWbBEUfSz5wIhAJbSuL5KIA1ZoAc9dKLD1hQHP9px4ccrg1vdc4J1N4vK","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQCY1wIqQc8QlFC0iZPkfufTKbR4bx8GaSveohlEG1i0jwIhAOjJUgIbbIOCKmUQI7TjK5p7KKZLnGpm1o4zevwiWQKT","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":180511},"type":"module","engines":{"node":">=20"},"gitHead":"6241e368a3158378dc1d5745bffc5aeb8d326baf","scripts":{"test":"npm run build && node --test dist/test/codemem.test.js dist/test/interfaces.test.js","build":"tsc","prepare":"npm run build","prepublishOnly":"npm test"},"_npmUser":{"name":"threedu","email":"khang180424@gmail.com"},"repository":{"url":"git+https://github.com/ThreeDu/Codebase-Memory.git","type":"git"},"_npmVersion":"11.6.2","description":"Long-term codebase memory for AI coding agents: module map, entry points, and notes, served over CLI and MCP.","directories":{},"_nodeVersion":"24.11.1","dependencies":{"zod":"^4.6.7","typescript":"~5.9","@modelcontextprotocol/sdk":"^1.32.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"^26.6.6"},"_npmOperationalInternal":{"tmp":"tmp/codebase-memory_0.4.1_1793718186932_0.50433897557329","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"_id":"@threedu/codebase-memory@0.5.0","bin":{"codemem":"dist/src/cli.js"},"bugs":{"url":"https://github.com/ThreeDu/Codebase-Memory/issues"},"dist":{"shasum":"da168aac6a470c5656e3eea593f7287a089370ee","tarball":"https://registry.npmjs.org/@threedu/codebase-memory/-/codebase-memory-0.5.0.tgz","fileCount":13,"integrity":"sha512-ACyAmjAk9PjTLfCnde7Nw4TLAxoNtLLYeourwp7fj0K8BqRZD0YITgAXntfqwsz8AA0iBBQQAF9bRTYYILqV8A==","signatures":[{"sig":"MEYCIQDXQ8g7vAHXWlqTHA7LBUSHCI9rtn7IHqbfn30jpsvkYgIhANetyyYnuz/8RRwbytCzOJaJyNOi5ByoT3UAGzd1wfjb","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFlUn7JU5Ab3GrwxdjqGa8Ync6yzQYSn4HfHcSC7+s7QAiEAw40N3mEnjWnw/xZnd4Gw3H3VL4XCSCg1TWrU51ckI6s="}],"unpackedSize":193066},"name":"@threedu/codebase-memory","type":"module","author":{"name":"Khang"},"engines":{"node":">=20"},"gitHead":"6b393f8e9faa38ca27bb5c07d2458c706d5d7cf8","license":"MIT","scripts":{"test":"npm run build && node --test dist/test/codemem.test.js dist/test/interfaces.test.js","build":"tsc","prepare":"npm run build","prepublishOnly":"npm test"},"version":"0.5.0","_npmUser":{"name":"threedu","email":"khang180424@gmail.com"},"homepage":"https://github.com/ThreeDu/Codebase-Memory#readme","keywords":["mcp","model-context-protocol","ai-agents","code-index","codebase","claude-code","cursor"],"repository":{"url":"git+https://github.com/ThreeDu/Codebase-Memory.git","type":"git"},"_npmVersion":"11.6.2","description":"Long-term codebase memory for AI coding agents: module map, entry points, and notes, served over CLI and MCP.","directories":{},"maintainers":[{"name":"threedu","email":"khang180424@gmail.com"}],"_nodeVersion":"24.11.1","dependencies":{"zod":"^4.6.7","typescript":"~5.9","@modelcontextprotocol/sdk":"^1.32.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"^26.6.6"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/codebase-memory_0.5.0_1794412360741_0.6694663086528813"}}},"time":{"created":"2026-10-31T13:56:01.601Z","modified":"2026-11-11T15:52:41.130Z","0.0.0-stage":"2026-10-31T13:56:01.601Z","0.2.0":"2026-10-31T13:56:56.981Z","0.2.2":"2026-11-01T12:59:44.358Z","0.3.0":"2026-11-01T14:34:11.467Z","0.4.0":"2026-11-03T09:38:41.384Z","0.4.1":"2026-11-03T15:03:07.038Z","0.5.0":"2026-11-11T15:52:40.809Z"},"bugs":{"url":"https://github.com/ThreeDu/Codebase-Memory/issues"},"author":{"name":"Khang"},"license":"MIT","homepage":"https://github.com/ThreeDu/Codebase-Memory#readme","keywords":["mcp","model-context-protocol","ai-agents","code-index","codebase","claude-code","cursor"],"repository":{"url":"git+https://github.com/ThreeDu/Codebase-Memory.git","type":"git"},"description":"Long-term codebase memory for AI coding agents: module map, entry points, and notes, served over CLI and MCP.","maintainers":[{"name":"threedu","email":"khang180424@gmail.com"}],"readme":"# Codebase-Memory\r\n\r\nLong-term memory for a codebase, so AI coding agents pick up its architecture without re-scanning everything.\r\n\r\n- **Module map**: every TS/JS, Python, Go, Java, Rust, C/C++, and C# file with its resolved imports and packages, plus its entry points and most depended-on modules.\r\n- **Symbols**: the functions, classes, and methods each file defines, which names it takes from which file, and which of those each function calls, so you can ask where `ChurnPredictor` is defined and which functions use it.\r\n- **Notes**: architecture decisions, code conventions, and bugs that were already fixed, each attached to the files or folders it's about. Comments tagged `WHY:`, `NOTE:`, `HACK:`, `IMPORTANT:`, `RATIONALE:` or `DECISION:` in the code count too, attached to the function they describe (credential-shaped strings in them are redacted).\r\n- **Incremental**: unchanged files aren't even read (same modification time and size), only changed content is re-parsed, and after an edit only the files around it are re-resolved. Tested on Kubernetes, LLVM, MongoDB, VS Code, Next.js, Godot, Django, React and Express.\r\n- **Hooks (Claude Code)**: optional. Each session starts with a short brief (every note, entry points, most depended-on files), again after `/clear` and `/compact`; opening a file with Read adds that file's notes, importers and API links. `codemem hooks` prints the settings.\r\n- **Selective context**: an agent asks about a file, folder, or keyword and gets back only the relevant notes, plus those files with their imports and importers.\r\n- **API links**: HTTP requests (`fetch`, `axios`, `requests`, `httpx`, and your own client functions wrapping them, like `apiClient(url, opts)`) are matched to the routes serving them (Express, Flask, FastAPI), so a frontend page is linked to the backend route it calls, and a backend to the service it calls. They show in `context`, `affected` and the graph (dashed edges). On a React + Express + Flask app: 91 of 91 requests linked.\r\n\r\nEverything lives in `.codemem/` inside the target repo (`index.json`, `notes.json`, `map.md`). Commit `notes.json` (and `map.md` if you like) so every agent and teammate shares the same memory; `index.json` is a cache that rebuilds itself, and on a big repo it's 100MB+, so leave it out of git. Agents without MCP can simply read `.codemem/map.md`.\r\n\r\nFull installation and usage guide, with examples for every command: [docs/USAGE.md](docs/USAGE.md).\r\n\r\n## Install\r\n\r\nFrom npm (gives you the `codemem` command):\r\n\r\n```bash\r\nnpm install -g @threedu/codebase-memory\r\n```\r\n\r\nOr without installing, `npx -y @threedu/codebase-memory <command>`. The latest code from GitHub runs with `npx -y github:ThreeDu/Codebase-Memory <command>`; to install it as `codemem`, clone it, run `npm install` (builds too), then `npm link`. (`npm install -g github:...` doesn't work: npm skips the build tools when installing a git package globally.) Needs Node.js 20+.\r\n\r\n## CLI\r\n\r\n```bash\r\ncodemem index path/to/repo\r\n```\r\n\r\n| Command | What it does |\r\n|---|---|\r\n| `index [dir]` | Create or update the memory (incremental) |\r\n| `map` | Print the project map |\r\n| `context <file\\|folder\\|symbol\\|keyword> [--budget N]` | Focused context, cut at N chars (default 8000) |\r\n| `symbol <name\\|Class.method>` | Where a function/class is defined and which files and functions use it |\r\n| `read <name\\|Class.method>` | Print just that function/class/method's source, with its line range |\r\n| `search <words...> [--limit N]` | Find functions/classes/methods by a rough name or a few words (`payment webhook`, `parseConfig`); code ranks before tests |\r\n| `affected <files...> [--stdin] [--depth N] [--quiet]` | Files and tests that depend on these files, through several import hops. `git diff --name-only \\| codemem affected --stdin --quiet` lists the tests to run |\r\n| `note add --kind decision\\|convention\\|fix [--paths a,b] \"<title>\" [\"<body>\"]` | Save a note |\r\n| `note edit <id> [--kind K] [--title T] [--body B] [--paths a,b]` | Change only the given fields of a note |\r\n| `note rm <id>` | Delete a note |\r\n| `note list` | List notes; `⚠ missing` marks notes whose files/folders were renamed or deleted |\r\n| `graph [--no-open]` | Re-index, write `.codemem/graph.html`, and open it in the browser |\r\n| `watch` | Keep `map.md` and `graph.html` updated as code changes (refresh the browser to see it) |\r\n| `mcp` | Run as an MCP server on stdio |\r\n\r\nAll commands accept `--root <dir>` (default: the current directory). From a clone without `npm link`, run `node dist/src/cli.js` instead of `codemem`.\r\n\r\n## Graph view\r\n\r\n`codemem graph` opens an interactive map of the whole codebase: folders are boxes (single-folder chains merged into one), files are dots colored by language with a legend (bigger = more importers, orange ring = entry point, faded and dashed = test), arrows are imports. The page is dark. Hover for a summary; click a file to highlight what it imports in blue and what imports it in green (labelled with the imported names), and its functions/classes, what each one calls, and its notes in the side panel; click a folder for its files; **Hide tests** shows just the app's own structure; type a file or function name in the search box and press Enter to jump to it. The page is a single file with the data embedded (it loads Cytoscape and its fcose layout from cdnjs/jsDelivr, so it needs internet). It's regenerated on every run, so you may want `.codemem/graph.html` in the target repo's `.gitignore`.\r\n\r\n## Use from Claude Code (MCP)\r\n\r\nWith `codemem` installed:\r\n\r\n```bash\r\nclaude mcp add codemem -- codemem mcp --root .\r\n```\r\n\r\nOn Windows use `-- cmd /c codemem mcp --root .`. Without installing anything: `-- npx -y @threedu/codebase-memory mcp --root .` (Windows: `-- cmd /c npx -y @threedu/codebase-memory mcp --root .`). From a clone: `-- node /path/to/Codebase-Memory/dist/src/cli.js mcp --root .`. Other MCP clients (Cursor, Codex, Gemini CLI, ...) run the same command; see [docs/USAGE.md](docs/USAGE.md#using-it-from-ai-agents-mcp).\r\n\r\nTools: `reindex`, `get_map`, `get_context`, `find_symbol`, `search_symbols`, `read_symbol` (also shows who uses it and whether a test does), `affected`, `add_note`, `update_note`, `remove_note`. Several agents (or an agent and `codemem watch`) can use one repo at once: files are written atomically and notes under a lock. A good line for the target repo's `CLAUDE.md`/`AGENTS.md`:\r\n\r\n> Before working on an area, call `get_context` for it; find code by a rough name with `search_symbols`, and read a single function with `read_symbol` instead of the whole file. Record decisions, conventions, and non-obvious bug fixes with `add_note`; fix or remove notes marked `⚠ missing` or no longer true.\r\n\r\nTo have every session start with the notes and the shape of the repo, without the agent having to ask, add the hooks: run `codemem hooks` and merge its output into `.claude/settings.json` (needs `codemem` on PATH; see [docs/USAGE.md](docs/USAGE.md#hooks-claude-code-context-without-asking)).\r\n\r\nOr give Claude Code the full usage guide as a skill. With the package installed globally: `cp -r \"$(npm root -g)/@threedu/codebase-memory/skills/codemem\" ~/.claude/skills/` (see [docs/USAGE.md](docs/USAGE.md#or-install-the-skill-claude-code)).\r\n\r\n## Limits (v1)\r\n\r\n- Parses TS/JS (`.ts .tsx .mts .cts .js .jsx .mjs .cjs`, ES modules and CommonJS), Python (`.py`), Go (`.go`), Java (`.java`), Rust (`.rs`), C/C++ (`.c .h .cc .cpp .cxx .hh .hpp .hxx`), and C# (`.cs`).\r\n- C/C++: `#include \"x.h\"` is looked up next to the file, then (like `<x.h>`) as any repo file ending in that path; an included header also links to the file implementing it (`util.h` -> `util.c`, the same name next to it or the only one in the repo). Prototypes are skipped so calls go to the definition; `Foo::bar` is method `bar` of `Foo`. Definitions are expected at the top level or inside an unindented `namespace x {`.\r\n- C#: a file is linked to the files of each namespace in view (its own and its parents, plus every `using`) whose types it mentions; `namespace X { }` and file-scoped `namespace X;` both work. `global using` applies only to the file it's written in.\r\n- Go, Java, Rust, C/C++, C#: found by regex on conventionally formatted code (gofmt, rustfmt, top-level types at column 0). Go imports of the module in `go.mod` resolve to every non-test file in that package's folder; Java `a.b.C` resolves to the file ending in `a/b/C.java` under any source root; Rust follows `mod x;`, `use crate::/self::/super::`, groups, `as`, and `pub use` re-exports. Go and Java files are linked to files of their own package (same folder) whose functions/types they use. Braces inside block comments or multi-line strings can throw off a definition's end line.\r\n- Symbols: top-level functions, classes, methods, exported constants (TS/JS) and module CONSTANTS (Python). Calls are matched by name, so a method called through an instance (`obj.train()`) is not tracked; a default import or `module.exports = expr` is matched by its local name / the file name.\r\n- Python: imports and symbols are found by regex, and absolute imports are looked up from the importing file's folder up to the repo root (so a service folder like `ml-service/` works as its own source root), then `src/`.\r\n- TS/JS aliases: `paths` and `baseUrl` from every `tsconfig*.json` / `jsconfig.json` are applied to files under that config's folder; `extends` is not followed.\r\n- `context`, `symbol`, `read` and the MCP tools re-index before answering. With nothing changed that's a check of every file's modification time: about 1–2 s on Kubernetes (14k files), 6–9 s on LLVM (77k). After an edit the whole index file is rewritten, which costs more on huge repos (about 5 s on Kubernetes, 14 s on LLVM). `codemem watch` is the opt-in file watcher.\r\n- Skipped: build output (`dist`, `build`, `target`, `obj`) and vendored dependencies (`vendor`, `third_party`, `thirdparty`, `3rdparty`), besides whatever `.gitignore` excludes. Source files over 5 MB are listed but never read (on 9 big repos those were test data and constant tables; files of 1–5 MB, like LLVM's X86ISelLowering.cpp, are read).\r\n- Monorepos: a package of the repo imported by name (`shared/flags`, `@acme/core`) is linked to its files through its `package.json` `name` (npm/yarn/pnpm workspaces, Lerna, Nx, Turborepo); the bare name goes to its `main`/`module`/`exports[\".\"]`, or its source when that points into `dist/`. Pattern `exports` (`\"./*\"`) and bundler or Jest aliases (`resolve.alias`, `moduleNameMapper`) aren't followed.\r\n- Big repos: when listing every file would make `map.md` longer than about 40,000 characters, its Modules section lists folders instead (as deep as fits), and Entry points shows the first 60.\r\n\r\n## Develop\r\n\r\n```bash\r\nnpm test\r\n```\r\n","readmeFilename":"README.md"}