Memorix

Local-first shared memory layer for AI coding agents.
One project memory system for Claude Code, Codex, CodeBuddy Code, Cursor, Windsurf, Copilot, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, DeepSeek Harness, and any MCP-capable agent.

Shared Project Memory|MCP|Git Memory|Reasoning Memory|Plugins|Orchestration

Chinese|Install|Capabilities|Agents|Quick Start|Memory Model|memcode|Active Work|Docs

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

SeeIntegration Surfacesfor the current support matrix and what each generated file means.

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 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

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

For a manually managed Claude Code entry, add"alwaysLoad": trueinside thememorixserver object. This lets Claude Code expose Memorix tools during print-mode startup;memorix doctor agents --agent claudecan 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:

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

Stop the background service and remove hooks:

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

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

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" # Deliberate durable memory: create a candidate, then review it before it can enter a Workset. memorix memory long-term add --kind procedural --scope user --portability portable --title "Release verification preference" --text "Run focused tests and a packed-package smoke before publishing." --applicability "When publishing an npm package." memorix memory long-term qualify --id <id> --reason "The user explicitly confirmed this preference." memorix memory long-term approve --id <id> --reason "Reviewed for future local projects." 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. Usememorix identity joinormemorix identity use --agent-id <id>only when you intentionally need personal/team memory or coordinated task actions;memorix identity clearreturns the terminal to project scope.--as <active-agent-id>is the one-command alternative for scripts. Both camelCase and kebab-case flags are accepted.

Media is opt-in. An explicit local import is copied into Memorix's local data directory, hashed, and kept outside the Git worktree. It becomes normal memory only when you attach it. Memorix never captures every screenshot or tool output. An asset may be up to the configured media limit (100 MiB by default). Automatic vision analysis is deliberately capped at 20 MiB; a larger image is still kept and can be attached, but Memorix records a clear text fallback instead of sending an oversized payload to a model provider.

memorix media import --path ./architecture.png --json memorix media attach --asset <asset-id> --title "Architecture diagram" --json memorix media list --kind image --json memorix media show --asset <asset-id> --json memorix media remove --asset <asset-id> --force --json # Controlled derivations: explicit, bounded, and attachable to memory. memorix media derive-pdf --asset <asset-id> --attach --json memorix media derive-audio --asset <asset-id> --attach --json # Legacy image analysis now uses the same controlled asset lifecycle. memorix ingest image --path ./architecture.png --json

MiniMax image generation is a deliberate CLI operation. Video generation returns a durable job immediately; inspect or cancel that job rather than waiting in an agent request.

# Configure MINIMAX_API_KEY in your user environment or .env, never in Git. memorix media generate image --prompt "A clean system architecture diagram" --json # Image-to-image with a reference image (MiniMax image-01 / image-01-live): memorix media generate image --prompt "Keep the subject, change the background" --image ./reference.png --json memorix media generate video --prompt "A short product walkthrough" --json memorix media status --job <media-job-id> --json memorix media cancel --job <media-job-id> --json

memorix_mediais the compact MCP companion in every profile, includingmicro. It supports import, attach, list, show, PDF/audio derivations, generation, and job status. MCP image and video generation are disabled by default because they may incur provider costs. SetMEMORIX_MCP_MEDIA_GENERATION=1only after you deliberately want an agent to request billed MiniMax output. The normal OpenRouter text embedding lane is still text-only; media vectors are created only by a provider that explicitly declares support for that modality. Text descriptions and attachments remain a useful ordinary retrieval fallback.

This opens memcode, a terminal coding agent that uses the same Memorix project memory as your MCP-connected agents.

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.

Long-term memory is deliberately not an automatic dump of every note. A source observation, Claim, workflow, session, and code snapshot keep their existing roles. An agent may askmemorix_storeto create an additional long-term record; an explicit request auto-qualifies and enters task briefs as a durable anchor, while hook-captured or Git-derived candidates stay pending until qualified. Approval stays an explicit operator review. Usememorix memory long-term approve|archive|supersedeto record the evidence-backed lifecycle. Only a manually created or user-confirmeduser + portableitem may be considered in another local project; project code, Git facts, tests, workflows, sessions, and observations cannot be promoted into portable user memory.

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. Use--brief-jsonwhen a CLI fallback needs the same bounded brief plus a receipt of what was selected or omitted;--jsonremains the detailed diagnostic form. 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 durable anchor carries adurable:<id>reference, so an agent can expand the full reviewed record throughmemorix_detailonly when needed. Keyword matches stay primary; when no reviewed durable item matches and an embedding provider is configured, Memorix makes one 1.8-second, no-retry semantic fallback for paraphrases or cross-language tasks. A slow or unavailable provider simply leaves the normal keyword-only Workset intact. A checkpoint is lifecycle evidence, not durable memory or a transcript backup. Agents should read the suggested files before trusting stored memory.

memorix servedefaults to--mode micro(9 tools) to keep MCP tool schemas small for agents.memorix setupwrites--mode liteinto the installed MCP config so every tool taught in the generated guidance is reachable. Use--mode teamfor coordination tools, or--mode fullfor advanced and compatibility tools such as checkpoint inspection.

Shortcuts and aliases:memorix search/remember/recentare direct query shortcuts,bg/bsstart the background service,hookruns the hook launcher, andmemorix config get|path|migrateinspects or migrates config files.

memorix orchestrateuses the current checkout for single-worker runs. When running multiple workers, it creates task worktrees under.worktrees/and merges successful task branches back. Use--isolatedto force worktree isolation for one worker,--no-worktreeto disable it,--allow-dirtyto run with uncommitted changes, and--no-auto-mergeto preserve task worktrees for manual review.

memcode is the terminal coding agent bundled with Memorix. It can read, edit, run commands, resume sessions, switch models, and use/memorycommands — 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.

one Git project -> one shared Memorix memory pool

Seedocs/MEMCODE.mdfor the memcode-specific guide.

[agent] provider = "openai" model = "gpt-4o" api_key = "..." [memory.llm] provider = "openai" model = "gpt-4o-mini" api_key = "..." [embedding] provider = "auto" [memory] inject = "minimal" formation = "active"

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, useprovider = "api",base_url = "https://openrouter.ai/api/v1", andmodel = "qwen/qwen3-embedding-8b". Memorix acceptsOPENROUTER_API_KEYfor that embedding endpoint;MEMORIX_EMBEDDING_API_KEYremains the explicit override.

For controlled MiniMax media generation, setMINIMAX_API_KEY(global) orMINIMAX_CN_API_KEY(China region) in your environment or.env. The media library never stores that key, a signed output URL, or base64 payloads. CLI generation is explicit; MCP generation additionally requiresMEMORIX_MCP_MEDIA_GENERATION=1.

Docker is for the HTTP service, not stdio MCP:

- 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 asprojectRootfor project-scoped Git and config behavior.

import { createMemoryClient } from 'memorix/sdk'; const client = await createMemoryClient({ 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();

LLM-friendly summaries:llms.txtandllms-full.txt.

git clone https://github.com/AVIDS2/memorix.git cd memorix npm install npm run lint npm test npm run build

Local code-knowledge graph + bi-temporal mistakes memory for AI coding agents. Serves a ranked structural packet instead of whole files on read/grep, and surfaces fixes your repo already reverted (mined from git history). Zero cloud, Apache-2.0.