# Locus > Persistent project-aware memory for AI coding tools. Built on MCP. Works with Codex, Claude Code, and other MCP-compatible clients. - **Type:** MCP server - **Install:** `agentstack add mcp-magnifico4625-locus` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Magnifico4625](https://agentstack.voostack.com/s/magnifico4625) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Magnifico4625](https://github.com/Magnifico4625) - **Source:** https://github.com/Magnifico4625/locus - **Website:** https://magnifico4625.github.io/locus/ ## Install ```sh agentstack add mcp-magnifico4625-locus ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Locus > Local persistent memory for AI coding tools. Built on MCP. Optimized for Codex CLI. [](https://www.npmjs.com/package/locus-memory) [](https://nodejs.org) [](LICENSE) [](https://modelcontextprotocol.io) [](docs/comparison.md) **Quick links:** [Install](#install-for-codex) · [Why Locus](#why-choose-locus) · [Competitive Snapshot](#competitive-snapshot) · [Full comparison](docs/comparison.md) ## What Locus Does AI coding agents forget project context between sessions. Locus gives them a local memory database they can query through MCP: - project structure: files, exports, imports - saved decisions: architecture choices, preferences, constraints - Codex conversation recall: recent work, errors, rejected alternatives, next steps - diagnostics: what is stored, what was imported, what capture mode is active Locus is local-first. It stores data on your machine, uses SQLite, and does not require a cloud account, hosted database, embeddings provider, or LLM call to write memory. ## Install For Codex ```bash npx -y locus-memory@latest install codex --yes ``` Restart Codex, then verify: ```bash npx -y locus-memory@latest doctor codex ``` Remove the Codex MCP entry while keeping local memory data: ```bash npx -y locus-memory@latest uninstall codex --yes ``` The installer adds the Locus MCP server, installs the Codex skill, sets practical `redacted` capture defaults, and pins the recurring MCP runtime to the installed package version. ## New In v3.7 **New in v3.7 / Track D:** Codex memory reliability. `memory_recall`, `memory_search`, and `memory_timeline` are scoped to the current project, date-aware recall reports searched buckets, `memory_calendar` gives day/week/month activity discovery, and `memory_project_state` summarizes current package/git/memory state before the agent relies on old context. Track C richer recall is still carried forward: `memory_recall` can summarize imported redacted Codex sessions, durable decisions, explicit `memory_remember` entries, rejected alternatives, validation facts, user style, and dated questions such as "what did we do yesterday?". If several matches are plausible, Locus returns `candidateGroups` so the agent can ask a focused clarification instead of guessing. Codex CLI is the primary validated path. Codex Desktop uses the same MCP model where exposed by the upstream surface, and the Track D marker acceptance validates the desktop MCP path when `LOCUS_CODEX_SURFACE=desktop` is set. Extension parity still depends on target-surface testing. ## Why Choose Locus | Need | Locus approach | | --- | --- | | One-command Codex setup | `npx -y locus-memory@latest install codex --yes` | | Local-only storage | SQLite under `$CODEX_HOME/memory/`, `~/.claude/memory/`, or `~/.locus/memory/` | | Low token cost | Writes happen locally; tokens are spent only when the agent recalls memory | | Privacy control | `metadata`, `redacted`, and `full` capture modes; `full` is explicit warning territory | | Project-aware memory | Structural scan plus durable decisions and conversation events | | Inspectability | `memory_status`, `memory_project_state`, `memory_doctor`, `memory_audit`, `memory_review` | | Cross-client base | Any MCP client can use the server; Codex and Claude Code have the strongest adapters today | ## Competitive Snapshot Locus is not trying to be a full agent runtime or cloud memory platform. It is a small local memory layer for coding agents, with Codex as the first-class product path. | Project | Main strength | Trade-off vs Locus | | --- | --- | --- | | [agentmemory](https://github.com/rohitg00/agentmemory) | Very broad coding-agent memory stack with many tools, hooks, viewer, and benchmark claims | Larger system surface; Locus is smaller, simpler, Codex-first, and ships as one npm MCP runtime | | [AIDE Memory](https://www.aide-memory.dev/) | Path-scoped local memory and very small context nudge | Locus focuses more on MCP tools, Codex JSONL import, diagnostics, and explicit recall UX | | [Mem0](https://github.com/mem0ai/mem0) | Popular general-purpose memory layer for AI agents with SDKs, hosted/self-hosted options, and benchmarks | Usually an application integration layer; Locus is ready-to-use for coding tools through MCP | | [Letta](https://github.com/letta-ai/letta) | Full stateful agent platform with advanced memory | More framework/runtime commitment; Locus plugs into existing tools instead of replacing them | | [Zep / Graphiti](https://github.com/getzep/graphiti) | Temporal knowledge graphs and production context infrastructure | Strong for app/enterprise memory; Locus is lighter and local by default for individual coding workflows | Full comparison: [docs/comparison.md](docs/comparison.md) ## Capture Modes | Mode | Use it when | What to expect | | --- | --- | --- | | `metadata` | You want safest diagnostics-first behavior | Minimal content recall | | `redacted` | You want practical Codex memory | Bounded snippets and keyword extraction with best-effort secret redaction | | `full` | You explicitly want maximum recall | More content stored locally after redaction; not risk-free | Recommended Codex settings: ```bash LOCUS_CODEX_CAPTURE=redacted LOCUS_CAPTURE_LEVEL=redacted ``` For product claims: `full` is maximum recall and must be treated as explicit opt-in, not a safe default. ## MCP Tools Locus exposes 17 MCP tools: | Tool | Purpose | | --- | --- | | `memory_recall` | Summary-first recall for questions about past work | | `memory_calendar` | Discover day/week/month activity buckets for a project and time range | | `memory_project_state` | Summarize project identity, package/git state, memory freshness, and active next steps | | `memory_search` | Full-text search across structure, decisions, and conversation events | | `memory_remember` | Save important decisions or preferences | | `memory_review` | Inspect durable memories, states, evidence, and topic keys | | `memory_import_codex` | Manually import Codex rollout JSONL sessions | | `memory_timeline` | Chronological event feed | | `memory_scan` | Index project structure | | `memory_explore` | Browse indexed project structure | | `memory_status` | Runtime state and Codex diagnostics | | `memory_doctor` | Actionable health checks | | `memory_audit` | Storage and privacy audit | | `memory_config` | Show effective configuration | | `memory_compact` | Prune old episodic entries | | `memory_forget` / `memory_purge` | Delete selected or all memory with safety confirmation | For broad period questions, use `memory_calendar` first. It defaults to `last_30d`, so agents should pass `this_month`, `last_month`, or an explicit range for user period questions. Date-scoped `memory_recall` reports searched date buckets, and current-project recall must not mix other project memories unless the user asks for global recall. ## Other Clients Locus is an MCP server, so it can run in Claude Code, Cursor, Windsurf, Cline, Zed, Claude Desktop, and similar clients. Current maturity: | Surface | Status | | --- | --- | | Codex CLI | Primary validated path | | Claude Code | Supported through hooks and shared runtime | | Codex desktop / extension | Desktop MCP marker path validated with `LOCUS_CODEX_SURFACE=desktop`; extension still requires target-surface validation | | Cursor / Windsurf / Cline / Zed | MCP tools work; passive conversation adapters are future work | Manual MCP fallback: ```bash codex mcp add locus -- node /path/to/locus/dist/server.js ``` ## Docs - Codex acceptance matrix: [docs/codex-acceptance-matrix.md](docs/codex-acceptance-matrix.md) - Codex VS Code extension notes: [docs/codex-vscode-extension.md](docs/codex-vscode-extension.md) - Future roadmap: [docs/roadmap/codex-next.md](docs/roadmap/codex-next.md) - Release notes: [docs/releases/v3.7.0.md](docs/releases/v3.7.0.md) - Full comparison: [docs/comparison.md](docs/comparison.md) ## Development ```bash git clone https://github.com/Magnifico4625/locus.git cd locus npm install npm run check npm run build ``` ## License MIT — see [LICENSE](LICENSE). ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Magnifico4625](https://github.com/Magnifico4625) - **Source:** [Magnifico4625/locus](https://github.com/Magnifico4625/locus) - **License:** MIT - **Homepage:** https://magnifico4625.github.io/locus/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-magnifico4625-locus - Seller: https://agentstack.voostack.com/s/magnifico4625 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.