Local-first persistent project memory for AI coding agents across MCP clients and sessions.
io.github.AVIDS2/memorix (MCP)
Local-first persistent project memory for AI coding agents across MCP clients and sessions. The MCP server enables shared recall of project context in a way that persists between sessions, supporting consistent behavior for agents interacting through different MCP clients.
🛠️ Key Features
Local-first persistent project memory
Shared across MCP clients
Persists across agent sessions
🚀 Use Cases
Store and reuse project context for AI coding agents
Maintain continuity when switching MCP clients
Keep memory available across repeated coding sessions
⚡ Developer Benefits
Consistent project context across MCP client connections
Reduced need to re-create prior context each session
Local-first persistence for memory continuity
⚠️ Limitations
Limited description available: no additional tool details, capabilities, or configuration information provided
Local-first shared memory layer for AI coding agents.
One project memory system for Claude Code, Codex, Cursor, Windsurf, Copilot, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, and any MCP-capable agent.
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
Memorix is local-first. SQLite is the canonical store, Orama handles search, and LLM-backed formation/embedding is optional. Without model keys, Memorix still works with local full-text retrieval.
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
Searchable facts, fixes, gotchas, session summaries, and implementation notes scoped to the current Git project
memorix memory, MCP memory tools
Code State and Code Memory
Versioned local code snapshots, file/symbol links, and freshness checks. The built-in Lite index is always honest about its limits; an already-indexed local CodeGraph can add a bounded semantic outline
memorix codegraph, 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, and diagnostics
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()
Works with every agent
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.
Claude Code Claude Code official plugin + MCP + hooks + skills
Codex CLI Codex CLI official plugin + MCP + AGENTS.md
Works with agents that speak MCP, expose hooks/rules, or support plugin/package entries. One local-first memory layer shared across all of them.
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, 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
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, Docker, or multiple clients.
Install
Requirements:
Node.js >=22.18.0
Git, because project identity is derived from the real Git root
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.
Quick Start
Connect an existing agent
Use the setup command first. The global form is the normal one-time install:
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.
Oh-my-Pi: installs an omp.extensions package with extension hook events, a memorix command, official skills, and writes MCP config.
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:
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, Docker, or multiple clients using the same endpoint:
bash
memorix background start
Then point the client at:
text
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.
memorix uninstall reports MCP config entries for manual cleanup instead of silently editing every MCP file it finds.
Work from the CLI
bash
memorix --cwd /path/to/repo resume "continue release blocker"
memorix checkpoint list
memorix memory search --query "release blocker"
memorix memory --help# Optional: activate one local agent identity for personal/team records and coordination.
memorix identity join --agent-type codex --name codex-main
memorix memory store --text "private investigation note" --visibility personal
memorix task create --description "verify the release package"
memorix transfer export --format json --out ./.memorix-export.json
memorix transfer import --file ./.memorix-export.json
memorix reasoning search --query "why sqlite"
memorix git-hook --force
memorix ingest log --count 20
memorix workbench
The CLI is direct and does not depend on an MCP session. It binds to the current Git project, or to the project supplied with --cwd. Without an active identity it reads, writes, and exports project-visible memory only. Use memorix identity join or memorix identity use --agent-id <id> only when you intentionally need personal/team memory or coordinated task actions; memorix identity clear returns the terminal to project scope. --as <active-agent-id> is the one-command alternative for scripts. Both camelCase and kebab-case flags are accepted.
Use the bundled terminal agent
bash
memorix
# or
memcode
This opens memcode, a terminal coding agent that uses the same Memorix project memory as your MCP-connected agents.
Memory Model
Layer
Stores
Best for
Observation Memory
facts, gotchas, fixes, implementation notes
"How does this work?"
Reasoning Memory
rationale, alternatives, constraints, risks
"Why did we choose this?"
Git Memory
commit-derived engineering facts
"What changed and where?"
Code Memory
files, symbols, import edges, and memory-to-code freshness
"Which current code should I inspect first?"
Compact Continuity
recent host-native compact summaries or lifecycle markers
"What survived the last context compaction?"
Search is project-scoped by default. scope="global" searches across projects. The search boosts Git Memory for "what changed" questions and reasoning records for "why" questions.
memorix context "..." is the default Memory Autopilot entry. It builds a compact task-lensed brief for agents: bugfix tasks lean toward tests and repros, release tasks lean toward package/changelog/build checks, onboarding tasks lean toward docs and entry points, and stale or unrelated memories stay in warning lanes instead of flooding the prompt. A normal new task does not receive an old-session dump. For an explicit continuation, memorix resume "..." adds only the latest useful session summary, up to three readable durable anchors, and at most one recent source-labelled host compact checkpoint. A checkpoint is lifecycle evidence, not durable memory or a transcript backup. Agents should read the suggested files before trusting stored memory.
Runtime Modes
You want
Run
Install an agent integration package
memorix setup --agent <agent> --global
Check or repair an agent integration
memorix doctor agents --agent <agent>, memorix repair agents --agent <agent>
memorix serve defaults to --mode micro (7 tools) to keep MCP tool schemas small for agents. Use --mode lite for the extended solo memory surface, --mode team for coordination tools, or --mode full for advanced and compatibility tools such as checkpoint inspection.
memorix orchestrate uses the current checkout for single-worker runs. When running multiple workers, it creates task worktrees under .worktrees/ and merges successful task branches back. Use --isolated to force worktree isolation for one worker, --no-worktree to disable it, --allow-dirty to run with uncommitted changes, and --no-auto-merge to preserve task worktrees for manual review.
memcode
memcode is the terminal coding agent bundled with Memorix. It can read, edit, run commands, resume sessions, switch models, and use /memory commands — all backed by the same project memory as your MCP-connected agents.
Use it when you want a terminal agent with memory already wired in.
Use [memory.llm] and [embedding] for Memorix memory quality and retrieval. Use [agent] for the model memcode talks to while coding. Keep credentials in global config or environment variables, and do not commit secrets.
For OpenRouter embeddings, use provider = "api", base_url = "https://openrouter.ai/api/v1", and model = "qwen/qwen3-embedding-8b". Memorix accepts OPENROUTER_API_KEY for that embedding endpoint; MEMORIX_EMBEDDING_API_KEY remains the explicit override.
Docker
Docker is for the HTTP service, not stdio MCP:
bash
docker compose up --build -d
Then open:
dashboard: http://localhost:3211
MCP: http://localhost:3211/mcp
health: http://localhost:3211/health
The container must be able to access the repository path passed as projectRoot for project-scoped Git and config behavior.
SDK
Use Memorix directly from TypeScript:
ts
import { createMemoryClient } from'memorix/sdk';
const client = awaitcreateMemoryClient({ projectRoot: '/path/to/repo' });
await client.store({
entityName: 'auth-module',
type: 'decision',
title: 'Use JWT for API auth',
narrative: 'Chose JWT because the API is stateless and used by multiple clients.',
});
const results = await client.search({ query: 'auth decision' });
await client.close();
git clone https://github.com/AVIDS2/memorix.git
cd memorix
npm install
npm run lint
npm test
npm run build
Acknowledgements
Memorix draws from the MCP ecosystem and prior memory projects such as mcp-memory-service, MemCP, claude-mem, and Mem0. memcode is based on the Pi coding-agent codebase and adapts its terminal-agent model for the Memorix ecosystem.
