memorix

<p align="center"> <img src="https://raw.githubusercontent.com/AVIDS2/memorix/main/assets/readme-hero.svg" alt="Memorix" width="720"> </p> <h1 align="center">Memorix</h1> <p align="center"> <strong>Local-first shared memory layer for AI coding agents.</strong><br> One project memory system for Claude Code, Codex, CodeBuddy Code, Cursor, Windsurf, Copilot, Gemini CLI, OpenCode, Grok Build, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, DeepSeek Harness, WorkBuddy, and any MCP-capable agent. </p> <p align="center"> <a href="https://www.npmjs.com/package/memorix"><img src="https://img.shields.io/npm/v/memorix.svg?style=for-the-badge&logo=npm&color=cb3837" alt="npm"></a> <a href="https://www.npmjs.com/package/memorix"><img src="https://img.shields.io/npm/dm/memorix.svg?style=for-the-badge&logo=npm&label=monthly%20downloads&color=7c3aed" alt="monthly downloads"></a> <a href="https://github.com/AVIDS2/memorix/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/AVIDS2/memorix/ci.yml?style=for-the-badge&label=CI&logo=github" alt="CI"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-2563eb?style=for-the-badge" alt="license"></a> <a href="https://github.com/AVIDS2/memorix"><img src="https://img.shields.io/github/stars/AVIDS2/memorix?style=for-the-badge&logo=github&color=facc15" alt="stars"></a> </p> <p align="center"> <a href="https://registry.modelcontextprotocol.io/?q=io.github.AVIDS2%2Fmemorix">Listed in the official MCP Registry</a> <br> <a href="https://mcptoplist.com/server/io.github.AVIDS2%2Fmemorix"><img src="https://mcptoplist.com/badge/io.github.AVIDS2%2Fmemorix.svg" alt="View Memorix on MCP Toplist"></a> </p> <p align="center"> <strong>Shared Project Memory</strong> | <strong>MCP</strong> | <strong>Git Memory</strong> | <strong>Reasoning Memory</strong> | <strong>Plugins</strong> | <strong>Orchestration</strong> </p> <p align="center"> <a href="https://mem.rglens.com">Website</a> | <a href="README.zh-CN.md">Chinese</a> | <a href="#install">Install</a> | <a href="#capabilities">Capabilities</a> | <a href="#works-with-your-agent">Agents</a> | <a href="#quick-start">Quick Start</a> | <a href="#memory-model">Memory Model</a> | <a href="#memcode-bundled-terminal-agent">memcode</a> | <a href="ACTIVE_WORK.md">Active Work</a> | <a href="#docs">Docs</a> </p>

---

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

<h2 id="what-memorix-is"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-overview.svg"><img src="assets/tags/section-overview.svg" alt="Memorix" height="32" /></picture></h2>

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 |

<h2 id="works-with-your-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-agents.svg"><img src="assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>

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.

<table> <tr> <td align="center" width="12.5%"> <a href="https://claude.com/product/claude-code"><img src="https://github.com/anthropics.png?size=120" alt="Claude Code" width="48" height="48"></a><br> <strong>Claude Code</strong><br> _{official plugin + MCP + hooks + skills} </td> <td align="center" width="12.5%"> <a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48"></a><br> <strong>Codex CLI</strong><br> _{official plugin + MCP + AGENTS.md} </td> <td align="center" width="12.5%"> <a href="https://github.com/features/copilot"><img src="https://github.githubassets.com/images/modules/site/copilot/copilot.png" alt="GitHub Copilot CLI" width="48" height="48"></a><br> <strong>GitHub Copilot CLI</strong><br> _{plugin + MCP + hooks + skills} </td> <td align="center" width="12.5%"> <a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48"></picture></a><br> <strong>Cursor</strong><br> _{MCP + rules + skills} </td> <td align="center" width="12.5%"> <a href="https://windsurf.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/windsurf-dark.svg"><img src="https://svgl.app/library/windsurf-light.svg" alt="Windsurf" width="48" height="48"></picture></a><br> <strong>Windsurf</strong><br> _{MCP + rules + hooks} </td> <td align="center" width="12.5%"> <a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48"></a><br> <strong>Gemini CLI</strong><br> _{extension + MCP + hooks + skills} </td> </tr> <tr> <td align="center" width="12.5%"> <a href="https://github.com/opencode-ai/opencode"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/opencode-dark.svg"><img src="https://svgl.app/library/opencode.svg" alt="OpenCode" width="48" height="48"></picture></a><br> <strong>OpenCode</strong><br> _{local plugin + MCP + skills + AGENTS.md} </td> <td align="center" width="12.5%"> <a href="https://pi.dev"><img src="https://pi.dev/favicon.svg" alt="pi coding agent" width="48" height="48"></a><br> <strong>pi coding agent</strong><br> _{package + extension + skill} </td> <td align="center" width="12.5%"> <a href="https://kiro.dev"><img src="https://kiro.dev/icon.svg" alt="Kiro" width="48" height="48"></a><br> <strong>Kiro</strong><br> _{MCP + steering + hooks} </td> <td align="center" width="12.5%"> <a href="https://antigravity.google"><img src="https://antigravity.google/assets/image/antigravity-logo.png" alt="Antigravity" width="48" height="48"></a><br> <strong>Antigravity</strong><br> _{plugin + MCP + hooks + skills} </td> <td align="center" width="12.5%"> <a href="https://www.trae.ai"><img src="https://github.com/Trae-AI.png?size=120" alt="Trae" width="48" height="48"></a><br> <strong>Trae</strong><br> _{MCP + project rules} </td> <td align="center" width="12.5%"> <img src="https://raw.githubusercontent.com/AVIDS2/memorix/main/assets/logo.png" alt="memcode" width="48" height="48"><br> <strong>memcode</strong><br> _{bundled terminal agent} </td> </tr> <tr> <td align="center" width="12.5%"> <a href="https://docs.openclaw.ai"><img src="https://raw.githubusercontent.com/openclaw/openclaw/main/ui/public/favicon.svg" alt="OpenClaw" width="48" he