{"id":51088961,"url":"https://github.com/AVIDS2/memorix","last_synced_at":"2026-07-12T04:00:51.567Z","repository":{"id":363245190,"uuid":"1157705791","full_name":"AVIDS2/memorix","owner":"AVIDS2","description":"Open-source cross-agent memory layer for coding agents via MCP. Compatible with Claude Code, Codex, Cursor, Windsurf, Gemini CLI, Antigravity, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Copilot, Kiro, OpenCode, and Trae.","archived":false,"fork":false,"pushed_at":"2026-07-07T10:56:35.000Z","size":11125,"stargazers_count":525,"open_issues_count":5,"forks_count":40,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-07-07T11:16:50.302Z","etag":null,"topics":["agent-memory","ai-coding","antigravity","claude-code","codex","coding-agents","copilot","cross-agent-memory","cursor","gemini-cli","hermes-agent","local-first","mcp","mcp-server","model-context-protocol","oh-my-pi","openclaw","opencode","typescript","windsurf"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AVIDS2.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-14T06:53:17.000Z","updated_at":"2026-07-07T10:56:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AVIDS2/memorix","commit_stats":null,"previous_names":["avids2/memorix"],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/AVIDS2/memorix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AVIDS2%2Fmemorix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AVIDS2%2Fmemorix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AVIDS2%2Fmemorix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AVIDS2%2Fmemorix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AVIDS2","download_url":"https://codeload.github.com/AVIDS2/memorix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AVIDS2%2Fmemorix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35381310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-coding","antigravity","claude-code","codex","coding-agents","copilot","cross-agent-memory","cursor","gemini-cli","hermes-agent","local-first","mcp","mcp-server","model-context-protocol","oh-my-pi","openclaw","opencode","typescript","windsurf"],"created_at":"2026-06-24T00:00:47.364Z","updated_at":"2026-07-12T04:00:51.550Z","avatar_url":"https://github.com/AVIDS2.png","language":"TypeScript","funding_links":[],"categories":["Catalog"],"sub_categories":["Context \u0026 Working-State Engineering"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/AVIDS2/memorix/main/assets/readme-hero.svg\" alt=\"Memorix\" width=\"720\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eMemorix\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eLocal-first shared memory layer for AI coding agents.\u003c/strong\u003e\u003cbr\u003e\n  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.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/memorix\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/memorix.svg?style=for-the-badge\u0026logo=npm\u0026color=cb3837\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/memorix\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/memorix.svg?style=for-the-badge\u0026logo=npm\u0026label=monthly%20downloads\u0026color=7c3aed\" alt=\"monthly downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/AVIDS2/memorix/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/AVIDS2/memorix/ci.yml?style=for-the-badge\u0026label=CI\u0026logo=github\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-2563eb?style=for-the-badge\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/AVIDS2/memorix\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/AVIDS2/memorix?style=for-the-badge\u0026logo=github\u0026color=facc15\" alt=\"stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eShared Project Memory\u003c/strong\u003e | \u003cstrong\u003eMCP\u003c/strong\u003e | \u003cstrong\u003eGit Memory\u003c/strong\u003e | \u003cstrong\u003eReasoning Memory\u003c/strong\u003e | \u003cstrong\u003ePlugins\u003c/strong\u003e | \u003cstrong\u003eOrchestration\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.zh-CN.md\"\u003eChinese\u003c/a\u003e |\n  \u003ca href=\"#install\"\u003eInstall\u003c/a\u003e |\n  \u003ca href=\"#capabilities\"\u003eCapabilities\u003c/a\u003e |\n  \u003ca href=\"#works-with-your-agent\"\u003eAgents\u003c/a\u003e |\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e |\n  \u003ca href=\"#memory-model\"\u003eMemory Model\u003c/a\u003e |\n  \u003ca href=\"#memcode-bundled-terminal-agent\"\u003ememcode\u003c/a\u003e |\n  \u003ca href=\"#docs\"\u003eDocs\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003ch2 id=\"what-memorix-is\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-overview.svg\"\u003e\u003cimg src=\"assets/tags/section-overview.svg\" alt=\"Memorix\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\nMemorix 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.\n\nUse Claude Code today, Codex tomorrow, and Cursor in the afternoon. The agent can change; the project memory stays the same.\n\n**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.\n\n| Problem | What Memorix adds |\n| --- | --- |\n| The next session forgets what the last session learned | Project-scoped memory, session summaries, timelines, and detail retrieval |\n| Different agents know different things | One local memory pool available through MCP, hooks, CLI, SDK, and the bundled terminal agent |\n| Git records what changed, but agents cannot recall it well | Git Memory turns commits into searchable engineering facts |\n| Architecture decisions disappear into old chats | Reasoning Memory stores why choices were made, with alternatives and trade-offs |\n| Static rule files drift | Gotchas, fixes, and project skills evolve from real work |\n| Parallel agent work gets messy | `memorix orchestrate` coordinates task context, handoffs, locks, verification, and review loops |\n\nMemorix 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.\n\n### Capabilities\n\nMemorix 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.\n\n| Capability | What it does | Entry point |\n| --- | --- | --- |\n| Memory Autopilot | A task-shaped project brief for a new agent session, with start files, trusted memories, cautions, and verification hints | `memorix context --task \"...\"`, `memorix_project_context` |\n| Observation Memory | Searchable facts, fixes, gotchas, session summaries, and implementation notes scoped to the current Git project | `memorix memory`, MCP memory tools |\n| Code Memory | File/symbol links and freshness checks so old memories point to current code or show up as suspect/stale | `memorix codegraph`, automatic context refresh |\n| Git Memory | Commit-derived engineering facts that answer what changed, where, and why it matters | `memorix ingest commit`, git hook |\n| Reasoning Memory | Design rationale, alternatives, trade-offs, and risks that should survive beyond one chat | `memorix reasoning`, memory formation |\n| Agent setup | One setup path for MCP, rules, hooks, skills, plugins, bundles, or extensions depending on the agent | `memorix setup --agent \u003cagent\u003e` |\n| Agent doctor | Checks whether agent MCP config and guidance are current, then repairs Memorix-owned entries when needed | `memorix doctor agents`, `memorix repair agents` |\n| Hooks and skills | Optional capture from supported agents, plus reusable project skills promoted from durable knowledge | `memorix hooks`, `memorix skills` |\n| Dashboard and HTTP | A local web UI and shared MCP endpoint for browsing memory, project state, teams, and diagnostics | `memorix dashboard`, `memorix background start` |\n| Orchestration and team work | Task planning, worker handoffs, file locks, messages, verification gates, and review loops | `memorix orchestrate`, `memorix team`, `memorix lock` |\n| memcode | A bundled terminal coding agent that already reads and writes the same project memory | `memorix`, `memcode` |\n| CLI and SDK | Scriptable access for automation, imports/exports, diagnostics, and custom integrations | `memorix ...`, `createMemoryClient()` |\n\n\u003ch2 id=\"works-with-your-agent\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-agents.svg\"\u003e\u003cimg src=\"assets/tags/section-agents.svg\" alt=\"Works with every agent\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\nMemorix 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.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://claude.com/product/claude-code\"\u003e\u003cimg src=\"https://github.com/anthropics.png?size=120\" alt=\"Claude Code\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eClaude Code\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003eofficial plugin + MCP + hooks + skills\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://github.com/openai/codex\"\u003e\u003cimg src=\"https://github.com/openai.png?size=120\" alt=\"Codex CLI\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eCodex CLI\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003eofficial plugin + MCP + AGENTS.md\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://github.com/features/copilot\"\u003e\u003cimg src=\"https://github.githubassets.com/images/modules/site/copilot/copilot.png\" alt=\"GitHub Copilot CLI\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eGitHub Copilot CLI\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003eplugin + MCP + hooks + skills\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://cursor.com\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://svgl.app/library/cursor_dark.svg\"\u003e\u003cimg src=\"https://svgl.app/library/cursor_light.svg\" alt=\"Cursor\" width=\"48\" height=\"48\"\u003e\u003c/picture\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eCursor\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003eMCP + rules + skills\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://windsurf.com\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://svgl.app/library/windsurf-dark.svg\"\u003e\u003cimg src=\"https://svgl.app/library/windsurf-light.svg\" alt=\"Windsurf\" width=\"48\" height=\"48\"\u003e\u003c/picture\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eWindsurf\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003eMCP + rules + hooks\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://github.com/google-gemini/gemini-cli\"\u003e\u003cimg src=\"https://github.com/google-gemini.png?size=120\" alt=\"Gemini CLI\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eGemini CLI\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003eextension + MCP + hooks + skills\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://github.com/opencode-ai/opencode\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://svgl.app/library/opencode-dark.svg\"\u003e\u003cimg src=\"https://svgl.app/library/opencode.svg\" alt=\"OpenCode\" width=\"48\" height=\"48\"\u003e\u003c/picture\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eOpenCode\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003elocal plugin + MCP + skills + AGENTS.md\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://pi.dev\"\u003e\u003cimg src=\"https://pi.dev/favicon.svg\" alt=\"pi coding agent\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003epi coding agent\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003epackage + extension + skill\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://kiro.dev\"\u003e\u003cimg src=\"https://kiro.dev/icon.svg\" alt=\"Kiro\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eKiro\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003eMCP + steering + hooks\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://antigravity.google\"\u003e\u003cimg src=\"https://antigravity.google/assets/image/antigravity-logo.png\" alt=\"Antigravity\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eAntigravity\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003eplugin + MCP + hooks + skills\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://www.trae.ai\"\u003e\u003cimg src=\"https://github.com/Trae-AI.png?size=120\" alt=\"Trae\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eTrae\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003eMCP + project rules\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/AVIDS2/memorix/main/assets/logo.png\" alt=\"memcode\" width=\"48\" height=\"48\"\u003e\u003cbr\u003e\n\u003cstrong\u003ememcode\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003ebundled terminal agent\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://docs.openclaw.ai\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/openclaw/openclaw/main/ui/public/favicon.svg\" alt=\"OpenClaw\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eOpenClaw\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003ebundle + MCP + hooks + skills\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://hermes-agent.nousresearch.com\"\u003e\u003cimg src=\"https://hermes-agent.nousresearch.com/icon.png\" alt=\"Hermes Agent\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eHermes Agent\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003eplugin + MCP + hooks + skills\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://omp.sh\"\u003e\u003cimg src=\"https://omp.sh/favicon.png\" alt=\"Oh-my-Pi\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eOh-my-Pi\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003epackage + MCP + hooks + skills\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\" width=\"12.5%\"\u003e\n\u003ca href=\"https://modelcontextprotocol.io\"\u003e\u003cimg src=\"https://github.com/modelcontextprotocol.png?size=120\" alt=\"Any MCP Client\" width=\"48\" height=\"48\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003cstrong\u003eAny MCP Client\u003c/strong\u003e\u003cbr\u003e\n\u003csub\u003estdio or HTTP MCP\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eWorks with agents that speak MCP, expose hooks/rules, or support plugin/package entries. One local-first memory layer shared across all of them.\u003c/sub\u003e\n\u003c/p\u003e\n\nIntegration surfaces:\n\n| Surface | What it does | Memorix entry |\n| --- | --- | --- |\n| Setup command | Installs the recommended one-time user-level Memorix integration | `memorix setup --agent \u003cagent\u003e --global` |\n| MCP | Gives an agent compact Memorix tools for project context, search, detail retrieval, storage, and resolution | bundled in setup packages or `memorix serve` |\n| Usage guidance | Teaches an agent when and how to use Memorix without forcing memory lookup on every prompt | bundled or generated by `memorix setup` |\n| Hooks | Optional auto-capture of prompts, tool events, file edits, and session lifecycle events where the agent exposes hooks | bundled or generated by `memorix setup` |\n| 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 |\n| Extension | Installs extension files where the agent supports them | Gemini CLI |\n| Local plugin | Installs local plugin files where the agent loads them directly | OpenCode |\n| MCP/rules config | Writes MCP, rules, steering, guidance, or hook config for IDEs and agents that expose those surfaces | Cursor, Windsurf, Kiro, Trae |\n| Skills | Turns durable project knowledge into reusable task guidance | `memorix skills` and `memorix_promote` |\n| memcode | Opens the bundled terminal agent that already uses Memorix memory | `memorix` or `memcode` |\n\nSee [Integration Surfaces](docs/INTEGRATIONS.md) for the current support matrix and what each generated file means.\n\nUse the same setup command without `--global` only when you intentionally want repo-local guidance, rules, or hooks in the current Git project.\n\nCLI, MCP, and HTTP are different entry points:\n\n- `memorix` CLI is the direct command surface for setup, memory search/store, Git Memory, import/export, dashboard, orchestration, diagnostics, and automation.\n- `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.\n- `memorix background start` / `memorix serve-http` run the HTTP service for a shared endpoint, dashboard, Docker, or multiple clients.\n\n\u003ch2 id=\"install\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-install.svg\"\u003e\u003cimg src=\"assets/tags/section-install.svg\" alt=\"Install\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\nRequirements:\n\n- Node.js `\u003e=22.18.0`\n- Git, because project identity is derived from the real Git root\n\nInstall and initialize:\n\n```bash\nnpm install -g memorix\nmemorix init --global                   # optional defaults\nmemorix setup --agent claude --global   # or codex, copilot, cursor, pi, gemini-cli, opencode,\n                                       # windsurf, kiro, antigravity, trae, openclaw, hermes, omp\n```\n\n`memorix init` is optional. It creates or updates TOML configuration:\n\n- `~/.memorix/config.toml` for global defaults\n- `\u003cgit-root\u003e/memorix.toml` for optional project overrides\n\nLegacy `memorix.yml`, `.env`, and `~/.memorix/config.json` are still read for compatibility, but new setup flows use TOML.\n\nIf you want repo-local guidance or hooks for a specific repository, run the same setup command from inside that repo without `--global`.\n\n\u003ch2 id=\"quick-start\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-quick-start.svg\"\u003e\u003cimg src=\"assets/tags/section-quick-start.svg\" alt=\"Quick Start\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\n### Connect an existing agent\n\nUse the setup command first. The global form is the normal one-time install:\n\n```bash\nmemorix setup --agent claude --global\nmemorix setup --agent codex --global\nmemorix setup --agent copilot --global\nmemorix setup --agent cursor --global\nmemorix setup --agent pi --global\nmemorix setup --agent gemini-cli --global\nmemorix setup --agent opencode --global\nmemorix setup --agent windsurf --global\nmemorix setup --agent kiro --global\nmemorix setup --agent antigravity --global\nmemorix setup --agent trae --global\nmemorix setup --agent openclaw --global\nmemorix setup --agent hermes --global\nmemorix setup --agent omp --global\n```\n\nWhat 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.\n\n- Claude Code: installs the Memorix plugin package, adds `CLAUDE.md` guidance, and enables hook capture when you do not pass `--noHooks`.\n- Codex: installs the Memorix plugin package, adds `AGENTS.md` guidance, and enables hook capture when you do not pass `--noHooks`.\n- GitHub Copilot CLI: installs the Copilot plugin package and official Memorix skills.\n- Pi: installs the user-level Pi package and official skills.\n- Cursor: writes Cursor MCP/rules/config entries in the chosen scope.\n- 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.\n- OpenCode: installs the local plugin file, `opencode.json`, skills, and `AGENTS.md` guidance.\n- Windsurf, Kiro, Trae: write the MCP/rules/hooks files the target supports.\n- 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`.\n- OpenClaw: installs an OpenClaw-compatible bundle with `.mcp.json`, official skills, and an OpenClaw `HOOK.md`/`handler.ts` hook pack.\n- 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.\n- Oh-my-Pi: installs an `omp.extensions` package with extension hook events, a `memorix` command, official skills, and writes MCP config.\n\nNeed a quieter install? Add `--noHooks` for targets where setup can control hook capture separately from the host's official package entry.\n\nIf you intentionally want repo-local guidance or hooks, run the same command inside that repository without `--global`.\n\nIf your agent only needs a manual MCP entry, use stdio:\n\n```json\n{\n  \"mcpServers\": {\n    \"memorix\": {\n      \"command\": \"memorix\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\nHTTP 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:\n\n```bash\nmemorix background start\n```\n\nThen point the client at:\n\n```text\nhttp://localhost:3211/mcp\n```\n\nIn 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.\n\n### Uninstall\n\nPreview what will be removed:\n\n```bash\nmemorix uninstall --dry-run\n```\n\nStop the background service and remove hooks:\n\n```bash\nmemorix uninstall --background --hooks\n```\n\nFull cleanup:\n\n```bash\nmemorix uninstall --yes --background --hooks --purge-data\nnpm uninstall -g memorix\n```\n\n`memorix uninstall` reports MCP config entries for manual cleanup instead of silently editing every MCP file it finds.\n\n### Work from the CLI\n\n```bash\nmemorix context --task \"continue release blocker\"\nmemorix memory search --query \"release blocker\"\nmemorix reasoning search --query \"why sqlite\"\nmemorix git-hook --force\nmemorix ingest log --count 20\nmemorix dashboard\n```\n\n### Use the bundled terminal agent\n\n```bash\nmemorix\n# or\nmemcode\n```\n\nThis opens memcode, a terminal coding agent that uses the same Memorix project memory as your MCP-connected agents.\n\n\u003ch2 id=\"memory-model\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-memory-model.svg\"\u003e\u003cimg src=\"assets/tags/section-memory-model.svg\" alt=\"Memory Model\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\n| Layer | Stores | Best for |\n| --- | --- | --- |\n| Observation Memory | facts, gotchas, fixes, implementation notes | \"How does this work?\" |\n| Reasoning Memory | rationale, alternatives, constraints, risks | \"Why did we choose this?\" |\n| Git Memory | commit-derived engineering facts | \"What changed and where?\" |\n| Code Memory | files, symbols, import edges, and memory-to-code freshness | \"Which current code should I inspect first?\" |\n\nSearch 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.\n\n`memorix context --task \"...\"` 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. Agents should read the suggested files before trusting stored memory.\n\n\u003ch2 id=\"runtime-modes\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-runtime.svg\"\u003e\u003cimg src=\"assets/tags/section-runtime.svg\" alt=\"Runtime Modes\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\n| You want | Run |\n| --- | --- |\n| Install an agent integration package | `memorix setup --agent \u003cagent\u003e --global` |\n| Check or repair an agent integration | `memorix doctor agents --agent \u003cagent\u003e`, `memorix repair agents --agent \u003cagent\u003e` |\n| Manually expose stdio MCP | `memorix serve` |\n| Run shared HTTP MCP plus dashboard | `memorix background start` |\n| Debug HTTP MCP in the foreground | `memorix serve-http --port 3211` |\n| Inspect or manage memory directly | `memorix memory`, `memorix reasoning`, `memorix session`, `memorix ingest` |\n| Use the bundled terminal agent | `memorix` or `memcode` |\n| Run orchestrated subagent work | `memorix orchestrate --goal \"...\"` |\n\n`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.\n\n`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.\n\n\u003ch2 id=\"memcode-bundled-terminal-agent\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-memcode.svg\"\u003e\u003cimg src=\"assets/tags/section-memcode.svg\" alt=\"memcode\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\nmemcode 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.\n\nUse it when you want a terminal agent with memory already wired in.\n\n```text\none Git project -\u003e one shared Memorix memory pool\n```\n\nSee [docs/MEMCODE.md](docs/MEMCODE.md) for the memcode-specific guide.\n\n\u003ch2 id=\"configuration\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-configuration.svg\"\u003e\u003cimg src=\"assets/tags/section-configuration.svg\" alt=\"Configuration\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\nMinimal `~/.memorix/config.toml`:\n\n```toml\n[agent]\nprovider = \"openai\"\nmodel = \"gpt-4o\"\napi_key = \"...\"\n\n[memory.llm]\nprovider = \"openai\"\nmodel = \"gpt-4o-mini\"\napi_key = \"...\"\n\n[embedding]\nprovider = \"auto\"\n\n[memory]\ninject = \"minimal\"\nformation = \"active\"\n```\n\nUse `[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.\n\nFor 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.\n\n\u003ch2 id=\"docker\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-docker.svg\"\u003e\u003cimg src=\"assets/tags/section-docker.svg\" alt=\"Docker\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\nDocker is for the HTTP service, not stdio MCP:\n\n```bash\ndocker compose up --build -d\n```\n\nThen open:\n\n- dashboard: `http://localhost:3211`\n- MCP: `http://localhost:3211/mcp`\n- health: `http://localhost:3211/health`\n\nThe container must be able to access the repository path passed as `projectRoot` for project-scoped Git and config behavior.\n\n\u003ch2 id=\"sdk\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-sdk.svg\"\u003e\u003cimg src=\"assets/tags/section-sdk.svg\" alt=\"SDK\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\nUse Memorix directly from TypeScript:\n\n```ts\nimport { createMemoryClient } from 'memorix/sdk';\n\nconst client = await createMemoryClient({ projectRoot: '/path/to/repo' });\n\nawait client.store({\n  entityName: 'auth-module',\n  type: 'decision',\n  title: 'Use JWT for API auth',\n  narrative: 'Chose JWT because the API is stateless and used by multiple clients.',\n});\n\nconst results = await client.search({ query: 'auth decision' });\nawait client.close();\n```\n\n\u003ch2 id=\"docs\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-docs.svg\"\u003e\u003cimg src=\"assets/tags/section-docs.svg\" alt=\"Docs\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\n| Start here | Use when |\n| --- | --- |\n| [Docs Map](docs/README.md) | You want the shortest route to the right guide |\n| [Setup Guide](docs/SETUP.md) | Installing, using `memorix setup`, choosing stdio vs HTTP |\n| [Integration Surfaces](docs/INTEGRATIONS.md) | Plugin packages, MCP, project rules, hooks, and skills support |\n| [Configuration](docs/CONFIGURATION.md) | TOML config, model lanes, compatibility files |\n| [API Reference](docs/API_REFERENCE.md) | MCP tools and CLI commands |\n| [Git Memory](docs/GIT_MEMORY.md) | Commit ingestion and searchable engineering truth |\n| [Docker](docs/DOCKER.md) | Containerized HTTP service |\n| [memcode](docs/MEMCODE.md) | Using the bundled terminal agent |\n| [Agent Playbook](docs/AGENT_OPERATOR_PLAYBOOK.md) | AI-facing execution guide for install, binding, hooks, and troubleshooting |\n| [Development](docs/DEVELOPMENT.md) | Contributing, testing, release checks |\n| [Changelog](CHANGELOG.md) | What changed in each release |\n\nLLM-friendly summaries: [llms.txt](llms.txt) and [llms-full.txt](llms-full.txt).\n\n\u003ch2 id=\"development\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-development.svg\"\u003e\u003cimg src=\"assets/tags/section-development.svg\" alt=\"Development\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\n```bash\ngit clone https://github.com/AVIDS2/memorix.git\ncd memorix\nnpm install\nnpm run lint\nnpm test\nnpm run build\n```\n\n\u003ch2 id=\"acknowledgements\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-acknowledgements.svg\"\u003e\u003cimg src=\"assets/tags/section-acknowledgements.svg\" alt=\"Acknowledgements\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\nMemorix 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.\n\n\u003ch2 id=\"license\"\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/tags/light/section-license.svg\"\u003e\u003cimg src=\"assets/tags/section-license.svg\" alt=\"License\" height=\"32\" /\u003e\u003c/picture\u003e\u003c/h2\u003e\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAVIDS2%2Fmemorix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAVIDS2%2Fmemorix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAVIDS2%2Fmemorix/lists"}