Memorix

---

Maintainer status and the current public work boundary live in ACTIVE_WORK.md. It is the repository's single living work tracker.

Memorix gives the AI coding agents you already use a shared, searchable project memory that survives new chats, IDE switches, terminal sessions, and handoffs. The memory lives under the Git project, not inside one chat window or one tool.

Use Claude Code today, Codex tomorrow, and Cursor in the afternoon. The agent can change; the project memory stays the same.

Use Memorix when you keep re-explaining the same project to a new agent session: the last session already figured something out, another IDE cannot see it, or a design decision is buried in a chat you cannot find anymore.

Problem	What Memorix adds
The next session forgets what the last session learned	Project-scoped memory, session summaries, timelines, and detail retrieval
Different agents know different things	One local memory pool available through MCP, hooks, CLI, SDK, and the bundled terminal agent
Git records what changed, but agents cannot recall it well	Git Memory turns commits into searchable engineering facts
Architecture decisions disappear into old chats	Reasoning Memory stores why choices were made, with alternatives and trade-offs
Static rule files drift	Gotchas, fixes, and project skills evolve from real work
Parallel agent work gets messy	memorix orchestrate coordinates task context, handoffs, locks, verification, and review loops

Memorix is local-first. SQLite is the canonical store. Small projects use the in-process Orama path; larger projects use a persistent SQLite FTS5 candidate index and, when available, an optional local LanceDB semantic shadow index. Both indexes are rebuildable and are never a limit on how many durable memories you can keep. LLM-backed formation and embedding remain optional.

Capabilities

Memorix is more than a memory store. It also installs agent integrations, keeps useful work events, turns commits into project facts, exposes a local control plane, and can coordinate multi-agent work when a task needs it.

Capability	What it does	Entry point
Memory Autopilot	A bounded task Workset with start files, current memory, source-backed knowledge, workflow starts, cautions, and verification. Compact JSON receipts keep fallback CLI use bounded too.	memorix context "..." --brief-json, memorix resume "..." --brief-json, memorix_project_context
Observation Memory	Searchable facts, fixes, gotchas, session summaries, and implementation notes scoped to the current Git project	memorix memory, MCP memory tools
Curated Long-term Memory	Deliberately reviewed episodic, semantic, and procedural memory with source evidence. Only an explicitly portable user item can cross local projects	memorix memory long-term
Code State and Code Memory	Versioned local code snapshots, source-backed TypeScript/JavaScript symbols and relations, file/symbol links, and freshness checks. Other languages keep the honest Lite fallback; an already-indexed local CodeGraph or SCIP result can add a bounded external outline without taking over the local index.	memorix codegraph status|refresh|init|sync, automatic context refresh
Git Memory	Commit-derived engineering facts that answer what changed, where, and why it matters	memorix ingest commit, git hook
Reasoning Memory	Design rationale, alternatives, trade-offs, and risks that should survive beyond one chat	memorix reasoning, memory formation
Knowledge Workspace	Review-gated source-backed claims, Markdown pages, and canonical project workflows; proposals never overwrite reviewed pages silently	memorix knowledge, memorix knowledge workflow
Agent setup	One setup path for MCP, rules, hooks, skills, plugins, bundles, or extensions depending on the agent	memorix setup --agent <agent>
Agent doctor	Checks whether agent MCP config and guidance are current, then repairs Memorix-owned entries when needed	memorix doctor agents, memorix repair agents
Hooks and skills	Optional capture from supported agents, plus reusable project skills promoted from durable knowledge	memorix hooks, memorix skills
Dashboard and HTTP	A local web UI and shared MCP endpoint for browsing memory, project state, teams, diagnostics, and preview-first cleanup, consolidation, deduplication, and retention actions	memorix dashboard, memorix background start
Orchestration and team work	Task planning, worker handoffs, file locks, messages, verification gates, and review loops	memorix orchestrate, memorix team, memorix lock
memcode	A bundled terminal coding agent that already reads and writes the same project memory	memorix, memcode
CLI and SDK	Scriptable access for automation, imports/exports, diagnostics, and custom integrations	memorix ..., createMemoryClient()
Optional multi-device sync	Privacy-filtered observation events with local SQLite kept canonical; default project scope, optional --scope user for every local project; GitHub JSONL, filesystem, S3, or Postgres relay	memorix sync store status|push|pull

Memorix connects through the interfaces each agent already supports: plugin packages, MCP, project rules, hooks, skills, or the bundled terminal agent. memorix setup chooses the right setup for each agent and keeps stdio MCP as the default transport.

Integration surfaces:

Surface	What it does	Memorix entry
Setup command	Installs the recommended one-time user-level Memorix integration	memorix setup --agent <agent> --global
MCP	Gives an agent compact Memorix tools for project context, search, detail retrieval, storage, and resolution	bundled in setup packages or memorix serve
Usage guidance	Teaches an agent when and how to use Memorix without forcing memory lookup on every prompt	bundled or generated by memorix setup
Hooks	Optional capture of prompts, tool events, file edits, session lifecycle events, and native compaction checkpoints where the agent exposes them	bundled or generated by memorix setup
Plugin or bundle package	Installs plugin, compatible-bundle, or package files where the agent supports them	Claude Code, Codex, CodeBuddy Code, GitHub Copilot CLI, Antigravity, OpenClaw, Hermes Agent, Oh-my-Pi, Pi
Extension	Installs extension files where the agent supports them	Gemini CLI
Local plugin	Installs local plugin files where the agent loads them directly	OpenCode
MCP/rules config	Writes MCP, rules, steering, guidance, or hook config for IDEs and agents that expose those surfaces	Cursor, Windsurf, Kiro, Trae, DeepSeek Harness, WorkBuddy
Skills	Turns durable project knowledge into reusable task guidance	memorix skills and memorix_promote
memcode	Opens the bundled terminal agent that already uses Memorix memory	memorix or memcode

See Integration Surfaces for the current support matrix and what each generated file means.

Use the same setup command without --global only when you intentionally want repo-local guidance, rules, or hooks in the current Git project.

CLI, MCP, and HTTP are different entry points:

• memorix CLI is the direct command surface for setup, memory search/store, Git Memory, import/export, dashboard, orchestration, diagnostics, and automation.
• memorix serve is the stdio MCP bridge used by IDEs and coding agents. Its default tool profile is micro, so agents see only the compact core tool set.
• memorix background start / memorix serve-http run the HTTP service for a shared endpoint, dashboard, VPS Docker deployment, or multiple clients.

Multi-device store sync is opt-in and separate from HTTP sharing. It never uploads the live SQLite database or WAL files. By default it only relays qualified project-visible observations for the current Git project; personal, agent-targeted, candidate, and ephemeral records stay local. Pass --scope user to include every local project. Set MEMORIX_SYNC_PROVIDER and inspect memorix sync store status --json before the first push.

Requirements:

• Node.js >=22.18.0
• Git, because project identity is derived from the real Git root

Install and initialize:

npm install -g memorix
memorix init --global                   # optional defaults
memorix setup --agent claude --global   # or codex, copilot, cursor, pi, gemini-cli, opencode,
                                       # codebuddy, windsurf, kiro, antigravity, trae, openclaw, hermes, omp

memorix init is optional. It creates or updates TOML configuration:

• ~/.memorix/config.toml for global defaults
• <git-root>/memorix.toml for optional project overrides

Legacy memorix.yml, .env, and ~/.memorix/config.json are still read for compatibility, but new setup flows use TOML.

If you want repo-local guidance or hooks for a specific repository, run the same setup command from inside that repo without --global. Codex is the exception: its supported path is the user-level plugin install, so Memorix leaves project .codex configuration alone.

Connect an existing agent

Use the setup command first. The global form is the normal one-time install:

memorix setup --agent claude --global
memorix setup --agent codex --global
memorix setup --agent copilot --global
memorix setup --agent cursor --global
memorix setup --agent pi --global
memorix setup --agent gemini-cli --global
memorix setup --agent opencode --global
memorix setup --agent windsurf --global
memorix setup --agent kiro --global
memorix setup --agent antigravity --global
memorix setup --agent trae --global
memorix setup --agent openclaw --global
memorix setup --agent hermes --global
memorix setup --agent codebuddy --global
memorix setup --agent omp --global
memorix setup --agent dsh --global
memorix setup --agent workbuddy --global
memorix setup --agent grok --global

What it installs depends on the target agent, but the goal is the same: make Memorix available wherever you open that agent without asking you to wire every repo by hand.

• Claude Code: installs the Memorix plugin package, adds CLAUDE.md guidance, and enables hook capture when you do not pass --noHooks.
• Codex: installs one user-level Memorix plugin with bundled stdio MCP, skills, and lifecycle hooks. It does not write project-local .codex config or change your model, approval, or sandbox settings. When Codex asks, review the plugin hook definition once with /hooks; --noHooks skips automatic capture.
• GitHub Copilot CLI: installs the Copilot plugin package and official Memorix skills.
• Pi: installs the user-level Pi package and official skills.
• Cursor: writes Cursor MCP/rules/config entries in the chosen scope.
• Gemini CLI: installs the extension package, GEMINI.md context, hooks, and skills. Antigravity CLI has an official Gemini CLI migration path, but Gemini CLI remains an active standalone target.
• OpenCode: installs the local plugin file, opencode.json, skills, and AGENTS.md guidance.
• Windsurf, Kiro, Trae: write the MCP/rules/hooks files the target supports.
• Antigravity: installs the official plugin package with plugin.json, mcp_config.json, hooks.json, rules, and skills under ~/.gemini/config/plugins/memorix or .agents/plugins/memorix.
• OpenClaw: installs an OpenClaw-compatible bundle with .mcp.json, official skills, and an OpenClaw HOOK.md/handler.ts hook pack.
• Hermes Agent: installs into Hermes home (%LOCALAPPDATA%\hermes on native Windows, ~/.hermes elsewhere, or HERMES_HOME), enables the plugin in config.yaml, registers plugin hooks, slash/CLI commands, skills, and writes MCP config.
• CodeBuddy Code: installs a user-scope local marketplace plugin under ~/.codebuddy/memorix-local with MCP, skills, and hooks. It does not change existing CodeBuddy model, permission, or settings files; CodeBuddy keeps third-party hook approval in its own /hooks flow.
• Oh-my-Pi: installs an omp.extensions package with extension hook events, a memorix command, official skills, and writes MCP config.
• DeepSeek Harness: writes a Memorix @deepseek-ai/dsh-mcp-client row into $DSH_HOME/cordis.patch.yml (default ~/.dsh/cordis.patch.yml), appends guidance to the harness AGENTS.md, and installs official skills under $DSH_HOME/skills. The row follows DSH's own shipped Memorix reference, so tools appear as mcp__memorix__*.
• WorkBuddy: writes a Memorix MCP server row into ~/.workbuddy/mcp.json (or <project>/.workbuddy/mcp.json for project installs) and appends guidance to AGENTS.md. Tools appear as mcp__memorix__*; there is no hooks surface.
• Grok Build: installs native lifecycle hooks under ~/.grok/hooks/memorix.json and guidance in ~/.grok/AGENTS.md. MCP stays host-owned by default; pass --mcp http to write [mcp_servers.memorix] with url = "http://localhost:3211/mcp". Project-local hooks require Grok /hooks-trust, while global hooks are trusted. Set GROK_HOME to use a custom Grok home.

Need a quieter install? Add --noHooks for targets where setup can control hook capture separately from the host's official package entry. It keeps MCP and guidance, but skips Memorix hook capture.

If you intentionally want repo-local guidance or hooks, run the same command inside that repository without --global.

If your agent only needs a manual MCP entry, use stdio:

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"]
    }
  }
}

For an npm-based MCP client or registry tester, use the complete command npx -y memorix serve. The serve argument matters: memorix without arguments opens the bundled memcode terminal agent when run by a human, while MCP clients should start the stdio server explicitly.

For a manually managed Claude Code entry, add "alwaysLoad": true inside the memorix server object. This lets Claude Code expose Memorix tools during print-mode startup; memorix doctor agents --agent claude can detect and repair a missing setting.

HTTP is not required for normal setup. Use it only when you intentionally want a shared background service, dashboard, VPS Docker deployment, or multiple clients using the same endpoint. Local development uses the Node service directly and does not require Docker:

memorix background start

Then point the client at:

http://localhost:3211/mcp

In HTTP mode, agents should bind the active repo explicitly with memorix_session_start(projectRoot=...) when the client can provide the workspace path. Git remains the final source of truth for project identity.

Uninstall

Preview what will be removed:

memorix uninstall --dry-run

Stop the background service and remove hooks:

memorix uninstall --background --hooks

Full cleanup:

memorix uninstall --yes --background --hooks --purge-data
npm uninstall -g memorix

memorix uninstall reports MCP config entries for manual cleanup instead of silently editing every MCP file it finds.

Work from the CLI

memorix --cwd /path/to/repo resume "continue release blocker"
memorix checkpoint list
memorix memory search --query "release blocker"
memorix memory --help