Locus

Local persistent memory for AI coding tools. Built on MCP. Optimized for Codex CLI.

Locus hero image

npm version Node.js License: MIT MCP Compare

Quick links: Install · Why Locus · Competitive Snapshot · Full comparison

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

npx -y locus-memory@latest install codex --yes

Restart Codex, then verify:

npx -y locus-memory@latest doctor codex

Remove the Codex MCP entry while keeping local memory data:

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 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 Path-scoped local memory and very small context nudge Locus focuses more on MCP tools, Codex JSONL import, diagnostics, and explicit recall UX
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 Full stateful agent platform with advanced memory More framework/runtime commitment; Locus plugs into existing tools instead of replacing them
Zep / 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

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:

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:

codex mcp add locus -- node /path/to/locus/dist/server.js

Docs

Development

git clone https://github.com/Magnifico4625/locus.git
cd locus
npm install

npm run check
npm run build

License

MIT — see LICENSE.