Locus

Persistent project-aware memory for AI coding tools. Built on MCP. Works with Claude Code, Codex CLI, Cursor, Windsurf, and any MCP-compatible client.

What is Locus?

AI coding tools lose context between sessions. Every new conversation starts from scratch — no memory of your architecture decisions, no awareness of which files exist, no record of what changed last week.

Locus solves this with three persistent memory layers:

• Structural — an auto-parsed map of files, exports, and imports, built from regex analysis of your codebase. Zero tokens consumed, always up to date.
• Semantic — decisions you save explicitly ("why JWT not sessions?", "why Postgres not Mongo?") with optional tags. Automatically redacted before storage.
• Episodic — a compressed history of what happened in each session: tools used, files changed, context captured via hooks.

New in v3.0 — Carbon Copy: Zero-cost passive capture of prompts, AI responses, and file changes via an inbox-based event protocol. A 4-phase ingest pipeline processes events into searchable conversation history — no tokens consumed on write, only on recall.

New in v3.3 — Codex Release: Codex now ships as a validated product line with manual import, auto-import before search, doctor/status diagnostics, skill sync, repo-local plugin packaging, and VS Code extension docs.

Locus stores metadata only by default. No raw file content is ever written to disk unless you explicitly opt in.

Compatibility

Locus is an MCP server. It works with any tool that supports the Model Context Protocol.

How it works: The MCP server provides 13 tools and 3 resources to any connected client. Storage location is auto-detected per client (~/.claude/memory/ for Claude Code, $CODEX_HOME/memory/ for Codex CLI, ~/.locus/memory/ for others). In Claude Code, three native hooks additionally capture conversation events into a local inbox for passive memory. In Codex CLI, the newest rollout session is auto-imported before memory_search in a bounded, debounced, best-effort way, and memory_import_codex remains available for explicit catch-up or filtered manual import.

Features

• 3 memory layers: structural (auto-parsed), semantic (user-curated), episodic (auto-captured)
• Carbon Copy: passive conversation capture via inbox-based event protocol
• 13 MCP tools for exploring, searching, remembering, and managing memory
• 3 auto-injected MCP resources (<3.5k tokens total)
• Incremental scanning: git-diff → mtime → full rescan strategies
• 4-layer security: metadata-only → file denylist → content redaction → audit UX
• FTS5 full-text search across all memory layers + conversation events
• Zero native dependencies — Node 22+ built-in sqlite, sql.js fallback
• Cross-platform: Windows, macOS, Linux

Quick Start

Prerequisites: Node.js >= 22.0.0

Claude Code (plugin — recommended)

# Install as a plugin
claude plugin install locus

# Or from local directory (for development)
claude --plugin-dir /path/to/locus

Once installed, Locus auto-injects 3 resources into every conversation — no configuration required. Three hooks automatically capture conversation events into a local inbox.

Codex CLI

Add Locus as an MCP server:

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

Or add directly to ~/.codex/config.toml:

[mcp_servers.locus]
command = "node"
args = ["/path/to/locus/dist/server.js"]

[mcp_servers.locus.env]
LOCUS_LOG = "error"

Repo-local plugin packaging is also available for local Codex onboarding:

• plugin bundle: plugins/locus-memory
• repo marketplace: .agents/plugins/marketplace.json
• plugin sync helper: npm run sync:codex-plugin

Note: Codex CLI storage goes to $CODEX_HOME/memory/. All 13 MCP tools and 3 resources work immediately. Before memory_search, Locus auto-imports the newest Codex rollout session with a local debounce window. memory_status now exposes structured Codex diagnostics, memory_doctor adds Codex-specific health checks, and memory_import_codex remains available when you want explicit control, filtered import, or manual catch-up across older sessions.
Validated against the current Codex docs generation and Codex CLI 0.120.0 surface as of April 13, 2026.

Manual MCP setup remains fully supported. The local plugin bundle is an optional packaging layer for repo-local onboarding, not a replacement requirement.

Recent Codex history becomes searchable automatically when you use memory_search.

Recommended Codex workflow:

• use memory_search first when recalling recent work, prior decisions, or recent Codex dialogue
• use memory_status to inspect codexAutoImport and codexDiagnostics if recent dialogue does not appear as expected
• use memory_doctor for actionable Codex checks when you need to diagnose session discovery, rollout readability, capture mode, or imported-event counts
• use memory_import_codex only for older sessions, filtered imports, or explicit manual catch-up
• use memory_remember for important architectural decisions and why they were made

Common Codex fixes:

• confirm CODEX_HOME points at the active Codex home directory
• confirm $CODEX_HOME/sessions/ exists and contains rollout-*.jsonl files
• confirm LOCUS_CODEX_CAPTURE is not set to off
• use memory_search first, then memory_status, then memory_doctor, and only then run memory_import_codex for manual catch-up

To keep the locally installed Codex skill aligned with the repo copy:

npm run sync:codex-skill

To keep the repo-local Codex plugin bundle aligned with the canonical skill:

npm run sync:codex-plugin

Import the latest Codex rollout session on demand:

memory_import_codex({"latestOnly":true})

Import only sessions for one project or session id:

memory_import_codex({"projectRoot":"C:\\Users\\Admin\\my-project"})
memory_import_codex({"sessionId":"sess_abc123"})
memory_import_codex({"since":1710000000000})

Codex VS Code Extension

The Codex VS Code extension uses the same Codex MCP configuration model as Codex CLI. In practice, this means Locus can work there through the same server setup, but MCP visibility in the extension may still depend on upstream preview behavior.

Treat Codex CLI as the primary validated path. If the extension does not expose Locus tools in a given build, that is an IDE integration boundary, not a separate Locus skill format.

Use the dedicated guide for setup, reload, verification, and troubleshooting:

• Codex VS Code Extension

Recommended diagnosis order in the extension:

• run memory_search first
• inspect memory_status
• inspect memory_doctor
• use memory_import_codex only for explicit manual catch-up

The repo-local plugin bundle can support local Codex onboarding here too, but manual MCP setup remains the documented fallback if extension/plugin behavior differs from Codex CLI in a given build.

Any MCP Client (Cursor, Windsurf, Cline, Zed, etc.)

Add Locus to your MCP configuration. The exact file depends on your tool:

Add this server entry:

{
  "mcpServers": {
    "locus": {
      "command": "node",
      "args": ["/path/to/locus/dist/server.js"],
      "env": {
        "LOCUS_LOG": "error"
      }
    }
  }
}

Note: When using Locus outside Claude Code, the MCP tools and resources work fully. Codex CLI additionally supports auto-import before memory_search plus manual session import via memory_import_codex. Adapter support for IDE log files in Cursor, Windsurf, and similar clients remains a future track.

For other MCP IDEs, Locus works through MCP tools/resources. The Codex-specific skill is not the primary integration mechanism there.

First Use

Use memory_scan to index your project structure on first run, then memory_search to explore what was found. Use memory_remember to save decisions as you make them.

Carbon Copy Capture (Claude Code)

By default, Locus captures tool use metadata (files read/written, tools used). To enable richer capture:

export LOCUS_CAPTURE_LEVEL=full      # prompts + AI responses (secrets redacted)
# or
export LOCUS_CAPTURE_LEVEL=redacted  # prompts as keywords only, no AI responses

Tools Reference

Extended Search Parameters (v3.0)

memory_search supports filters for conversation events:

Resources

Three MCP resources provide lightweight context at the start of every session (<3.5k tokens combined).

In Claude Code, resources are auto-injected. In other MCP clients, configure your tool to read these resources at session start.

Configuration

Environment Variables:

Capture Levels:

Note: Secrets are always redacted before storage regardless of capture level. At redacted level, user prompts are processed through RAKE keyword extraction — only statistically significant phrases are stored, not the full text. AI responses are never captured below full level. Defense-in-depth: hooks apply the captureLevel gate before writing to disk, and the ingest pipeline enforces it again as a second layer.

Default Configuration:

captureLevel:         metadata     # No raw file content stored
maxScanFiles:         10,000       # Skip projects with >10k files
maxFileSize:          1 MB         # Skip files larger than 1 MB
compressionThreshold: 10,000       # Compress episodic memory above 10k tokens
rescanThreshold:      30%          # Rescan if >30% files changed
fullRescanCooldown:   5 min        # Minimum interval between full rescans
minScanInterval:      10 sec       # Minimum interval between any scans

Search Engine: Locus uses SQLite FTS5 for full-text search when available. FTS5 indexes are self-healing — if the database was created without FTS5 and later opened with FTS5 available, indexes are auto-created and populated on startup. If your Node.js build doesn't include FTS5, search automatically falls back to LIKE queries (slower, less accurate). Run memory_doctor to check your search engine status.

Security

Locus uses a 4-layer security model:

1. Metadata-only — by default, only file paths, exports, and imports are stored. No raw file content is written to disk.
2. File denylist — .env, *.key, credentials.*, and other sensitive patterns are never indexed — enforced in both the structural scanner and the conversation ingest pipeline.
3. Content redaction — passwords, API keys, and tokens are automatically stripped from any content before storage. Redaction is applied twice: once in hooks before writing to disk, and again in the ingest pipeline before database storage.
4. Audit UX — the memory_audit tool shows exactly what is stored for the current project and flags any security concerns.

Architecture

+------------------------------------------+
|         AI Coding Tool Session           |
|  (Claude Code / Codex CLI / Cursor / ..) |
+------------+------------+----------------+
| Resource   | Resource   | Resource       |
| project    | decisions  | recent         |
| -map       |            |                |
+------------+------------+----------------+
|            12 MCP Tools                  |
+------------------------------------------+
|         Scanner (regex-based)            |
|    git-diff -> mtime -> full rescan      |
+------------------------------------------+
|     Storage: node:sqlite | sql.js        |
|     Client-aware path resolution:        |
|     Claude: ~/.claude/memory/locus-{h}/  |
|     Codex:  $CODEX_HOME/memory/locus-{h}/|
|     Other:  ~/.locus/memory/locus-{h}/   |
+------------------------------------------+
|   4-Phase Ingest Pipeline                |
|   Intake -> Filter -> Transform -> Store |
+------------------------------------------+
|   Adapters (event sources):              |
|   Claude Code hooks (v3.0)               |
|   Codex JSONL adapter + auto/manual      |
|   import into inbox before search        |
|   log-tailer / cli-wrapper (future)      |
|   -> inbox/ (atomic JSON events)         |
+------------------------------------------+

• Structural memory: regex-parsed exports and imports with confidence tagging
• Semantic memory: user-curated decisions, automatically redacted before storage
• Episodic memory: hook captures, lazy-compressed when the token count exceeds the threshold
• Conversation events: passively captured via adapters and indexed for search
• Storage: node:sqlite (Node 22+) primary, sql.js fallback
• FTS5: full-text search across all layers, auto-detected at startup
• Monorepo: @locus/core (MCP server) + @locus/shared-runtime (path resolution) + @locus/claude-code (hooks) + @locus/codex (skill + JSONL adapter + config)

FAQ

What works without hooks (Cursor, Windsurf, Cline, Zed)?

The MCP server is fully functional without hooks. Here's what you get:

Works out of the box:

These 10 tools cover the structural and semantic memory layers — your AI assistant will remember your project structure and decisions between sessions without any hooks.

Requires hooks (Claude Code only in v3.0):

The conversation layer (Carbon Copy) passively records what files you touched, what tools were used, and optionally what you asked — but this requires hooks to write events into the inbox. Without hooks, these features return empty results.

Bottom line: ~75% of tools work fully without hooks. The core value — "AI remembers your project between sessions" — works everywhere. Passive conversation history is the part that needs hooks, and broader IDE adapter support remains a future release track.

How is Locus different from CLAUDE.md?

They complement each other. CLAUDE.md is for static rules — coding conventions, architecture constraints, things that rarely change. Locus is for dynamic knowledge — current project state, evolving decisions, session history. Put "always use single quotes" in CLAUDE.md. Use memory_remember for "we chose JWT over sessions because the API is stateless".

Does Locus send my code anywhere?

No. Locus runs entirely locally. Your data is stored on your machine in a client-specific directory (~/.claude/memory/ for Claude Code, $CODEX_HOME/memory/ for Codex CLI, or ~/.locus/memory/ for other tools). Override with LOCUS_STORAGE_ROOT to share memory across clients. No network requests, no telemetry, no cloud storage. The MCP server communicates only with the AI client via stdio.

What about secrets and sensitive files?

Locus has 4 layers of protection: (1) metadata-only storage by default — no file content stored, (2) file denylist — .env, *.key, credentials are never indexed, (3) automatic secret redaction — API keys and passwords are stripped before storage, (4) memory_audit tool to review what's stored. See the Security section for details.

When will Cursor / Windsurf get full hook support?

The next Codex-focused release track will target richer conversational recall through redacted / full capture modes plus additional IDE adapters such as @locus/log-tailer. See the Roadmap below.

Roadmap

Development

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

npm test            # 863 tests (vitest)
npm run typecheck   # TypeScript strict mode
npm run lint        # Biome linter
npm run build       # Bundle -> dist/server.js (~1.1 MB)
npm run check       # All of the above

License

MIT — see LICENSE