Locus

Magnifico462515stars

Persistent project-aware memory for AI coding tools. Built on MCP. Works with Codex, Claude Code, and other MCP-compatible clients.

Databases Knowledge Memory

Install Run on PlugMCP

GitHub Website

Run on PlugMCP

1# Locus

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: MIT
Last checked: 2026-10-28

Stars: 15
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Locus?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Locus need an API key?

No required environment variable is listed on this record.

What transport does Locus use?

Locus runs locally over stdio.

When was Locus last checked?

Last checked 2026-10-28. Persistent project-aware memory for AI coding tools. Built on MCP. Works with Codex, Claude Code, and other MCP-compatible clients.

From the publisher

Documentation

Locus

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

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

Codex acceptance matrix: docs/codex-acceptance-matrix.md
Codex VS Code extension notes: docs/codex-vscode-extension.md
Future roadmap: docs/roadmap/codex-next.md
Release notes: docs/releases/v3.7.0.md
Full comparison: docs/comparison.md

Development

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

npm run check
npm run build

License

MIT — see LICENSE.

Locus

Magnifico462515stars

Persistent project-aware memory for AI coding tools. Built on MCP. Works with Codex, Claude Code, and other MCP-compatible clients.

Databases Knowledge Memory

Install Run on PlugMCP

GitHub Website

Run on PlugMCP

1# Locus

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: MIT
Last checked: 2026-10-28

Stars: 15
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Locus?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Locus need an API key?

No required environment variable is listed on this record.

What transport does Locus use?

Locus runs locally over stdio.

When was Locus last checked?

Last checked 2026-10-28. Persistent project-aware memory for AI coding tools. Built on MCP. Works with Codex, Claude Code, and other MCP-compatible clients.

From the publisher

Documentation

Locus

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

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

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

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

Codex acceptance matrix: docs/codex-acceptance-matrix.md
Codex VS Code extension notes: docs/codex-vscode-extension.md
Future roadmap: docs/roadmap/codex-next.md
Release notes: docs/releases/v3.7.0.md
Full comparison: docs/comparison.md

Development

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

npm run check
npm run build

License

MIT — see LICENSE.