# Memorix - Full AI-Facing Documentation Summary

> Local-first shared memory layer for AI coding agents.

Memorix is a TypeScript/Node.js project that gives AI coding agents persistent, project-aware memory. It targets software development workflows, not generic chat. It works across Claude Code, Codex, CodeBuddy Code, Cursor, Windsurf, GitHub Copilot CLI, Gemini CLI, OpenCode, Grok Build, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, DeepSeek Harness, WorkBuddy, and any agent that can speak MCP over stdio or HTTP. Integrations usually start with `memorix setup --agent <agent> --global`, which installs the recommended user-level package or config for that agent: plugin packages when supported, package or extension entries, MCP config, generated guidance, hooks, skills, or the bundled terminal agent.

If you are an AI coding agent helping a user install, operate, or troubleshoot Memorix, read `docs/AGENT_OPERATOR_PLAYBOOK.md` before taking action. It is the main reference for install, runtime selection, Git/project binding, MCP integration, hooks, and troubleshooting.

## 1.4 Multi-Dimensional Memory Model

Memorix is not a transcript dump. The normal agent path is `memorix_project_context` or `memorix context --task "..."`, which assembles a bounded task Workset: current Git/package facts, selected observations and reasoning, Code State freshness, source-backed claims, matching knowledge/workflow starts, cautions, and verification hints.

- **Observation, Reasoning, and Git Memory** preserve durable engineering facts.
- **Code State** records versioned local file, symbol, import, and memory-to-code links so prior evidence can be requalified when code moves.
- **Claim Ledger** keeps provenance, confidence, conflicts, and lifecycle state separate from prose.
- **Knowledge Workspace** compiles claims into reviewable Markdown proposals; it does not silently overwrite manually edited pages.
- **Canonical Workflows** represent project process once and render conservative agent-specific adapters only on explicit request.
- **Curated Long-Term Memory** keeps source-bound episodic, semantic, and procedural records separate from ordinary observations. A record is a candidate first, then can be explicitly qualified or approved; candidates, archived records, and superseded records never enter a Workset. A portable record is allowed only for explicit local `user + portable` knowledge with manual/user evidence. Project, team, Git, code, session, workflow, test, and observation evidence always remains project-bound. Keyword retrieval is primary; an optional semantic fallback is scope-filtered, limited to 1.8 seconds with no retry, and never blocks a lexical Workset when an embedding provider is slow or unavailable.
- **Lifecycle maintenance** uses durable, resumable jobs so indexing, claim requalification, knowledge compile/lint, retention, and consolidation do not turn an interactive MCP request into a corpus-sized foreground job.

The built-in CodeGraph Lite provider is a structural local fallback, not a complete semantic graph. If a project already has a healthy local CodeGraph index, `[codegraph].external_context = "auto"` can add a small validated semantic outline. Memorix never runs `codegraph init`, `index`, or `sync`, does not transmit the repository, and does not persist raw external code output.

## Entry Points

### Setup package

`memorix setup --agent <agent> --global` is the default agent integration command.

It installs the recommended Memorix integration for the target agent:

- Claude Code: local `memorix-local` marketplace plugin, plugin-bundled MCP, hooks, skills, plus `CLAUDE.md` guidance.
- Codex: local Personal marketplace plugin, plugin-bundled MCP, hooks, skills, plus `AGENTS.md` guidance. Setup also attempts `codex plugin add memorix@personal`.
- GitHub Copilot CLI: local Copilot CLI plugin package with MCP, hooks, and a Memorix skill. Setup attempts `copilot plugin install <local-path>`.
- Cursor: Cursor MCP config, `.cursor/rules/memorix.mdc`, skills, and hook guidance through Cursor's project config.
- Pi: user Pi package with a Memorix extension and skill. Setup also attempts `pi install <path> --approve`; project-local setup uses `-l`.
- Gemini CLI: local Gemini extension package with MCP and `GEMINI.md` context.
- OpenCode: local plugin file, `opencode.json` MCP config, OpenCode skill, and `AGENTS.md` guidance.
- Grok Build: native lifecycle hooks in `~/.grok/hooks/memorix.json` and `~/.grok/AGENTS.md` guidance. Grok owns its MCP configuration; project hooks require `/hooks-trust`.
- Multi-device sync: opt-in `memorix sync store status|push|pull` relays only qualified project-visible observation events. Local SQLite remains canonical; GitHub JSONL, filesystem, S3, and Postgres are transport options. Personal, agent-targeted, candidate, ephemeral, and other-project records are excluded by default.
- Windsurf, Kiro, Antigravity, Trae: MCP config plus rules/hooks where supported.
- DeepSeek Harness: MCP patch row (`$DSH_HOME/cordis.patch.yml`) plus `AGENTS.md` guidance and official skills.

Use:

```bash
npm install -g memorix
memorix init --global
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 grok --global
```

Manual `memorix integrate --agent <agent>` and `memorix hooks install --agent <agent>` are fallback commands for updating one generated integration without running the full setup package. Run setup without `--global` only when you intentionally want repo-local guidance, rules, or hooks for one project.

### MCP server

`memorix serve` starts the stdio MCP server.

Use it for manual MCP wiring when `memorix setup` is not being used:

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

### HTTP service

`memorix background start` starts a long-lived local HTTP MCP service and dashboard.

Endpoints:

- MCP: `http://localhost:3211/mcp`
- dashboard: `http://localhost:3211`
- health: `http://localhost:3211/health`

Use HTTP for a shared service, dashboard, Docker, or multiple-client setup. You don't need it for a single-agent setup. Use `memorix serve-http --port 3211` for foreground/debug mode.

Agents using HTTP in multi-project workflows should call `memorix_session_start(projectRoot=...)` with the absolute workspace path when available. Project identity still comes from Git.

### CLI

The CLI is for direct terminal use:

- `memorix memory`
- `memorix reasoning`
- `memorix session`
- `memorix retention`
- `memorix formation`
- `memorix audit`
- `memorix transfer`
- `memorix skills`
- `memorix team`
- `memorix task`
- `memorix message`
- `memorix lock`
- `memorix handoff`
- `memorix poll`
- `memorix receipt`
- `memorix sync`
- `memorix ingest`
- `memorix orchestrate`

Typical commands:

```bash
memorix memory search --query "release blocker"
memorix memory store --text "Auth tokens expire after 24h" --title "Auth token TTL" --entity auth --type decision
memorix memory long-term add --kind procedural --scope user --portability portable --text "Always run focused tests before a patch release"
memorix memory long-term qualify --id <memory-id> --reason "Verified in the release workflow"
memorix memory long-term approve --id <memory-id> --reason "Approved for local reuse"
memorix reasoning search --query "why sqlite"
memorix session start --agent codex-main --agentType codex
memorix receipt --json
memorix git-hook --force
memorix ingest log --count 20
memorix setup --agent cursor --global
memorix orchestrate --goal "Add authentication"
```

### Integration

`memorix setup` picks the right integration for the target agent. MCP is the common tool layer; agent-specific integrations add guidance or capture:

- plugin packages: Claude Code, Codex, and GitHub Copilot CLI
- package or extension entries: Pi package and Gemini CLI extension package
- local plugins: OpenCode local plugin file and skill
- project instructions and rules: AGENTS.md, GEMINI.md, Cursor rules, Windsurf rules, Kiro steering, Trae rules, DeepSeek Harness AGENTS.md
- hooks: agent event capture routed through `memorix hook`
- skills: durable project knowledge promoted into reusable task guidance

Use `docs/INTEGRATIONS.md` for the support matrix.

### memcode

`memorix` and `memcode` enter memcode, the bundled terminal agent that reads from and writes to the same Memorix project memory pool.

memcode can:

- read files, edit files, write files, run shell commands
- resume, continue, fork, label, and export coding sessions
- switch models and thinking levels
- load skills, prompt templates, themes, and extensions
- call Memorix memory tools directly
- capture prompts, tool events, assistant output, and runtime state through the Memorix hook pipeline

Common commands:

```bash
memorix
memcode
memcode -p "summarize this repo"
memcode -c
memcode -r
memcode --session <id>
memcode --fork <id>
memcode --model openai/gpt-4o
memcode --tools read,grep,find,ls -p "review src/"
```

Important TUI commands:

- `/memory status`
- `/memory search`
- `/memory show`
- `/memory stats`
- `/memory hooks`
- `/model switch`
- `/resume`
- `/tree`
- `/fork`
- `/session`
- `/git status`
- `/git diff`
- `/config`

memcode does not create a private memory silo. It uses the same project memory pool as external MCP-connected agents.

## Problems Memorix Solves

1. Session amnesia: the next chat forgets what the previous one learned.
2. IDE isolation: memory created in one coding tool is invisible to another.
3. Engineering truth loss: commits record what changed but not in a form agents can recall well.
4. Static rules drift: AGENTS.md, CLAUDE.md, and IDE rules become stale unless maintained.
5. Orchestrated subagent work: parallel agents need explicit task, handoff, message, lock, verification, and review state.

## Memory Layers

### Observation Memory

Reusable project knowledge:

- what changed
- how a subsystem works
- gotchas
- problem-solution notes
- implementation discoveries
- trade-offs

Typical types:

- `decision`
- `problem-solution`
- `gotcha`
- `how-it-works`
- `what-changed`
- `discovery`
- `trade-off`

### Reasoning Memory

Why a decision was made:

- alternatives considered
- constraints
- rationale
- expected outcome
- risks

Use this for architecture choices and non-trivial debugging decisions.

### Git Memory

Commit-derived engineering facts:

- source is `git`
- commit hash is preserved
- changed files are stored
- low-value commit noise can be filtered
- release/milestone commits can become durable memory

Git Memory is created with:

```bash
memorix git-hook --force
memorix ingest commit
memorix ingest log --count 20
```

## Retrieval Model

- Search is project-scoped by default.
- `scope="global"` intentionally searches across projects.
- Global hits can be opened through project-aware refs.
- Source-aware retrieval boosts Git Memory for "what changed" queries.
- Source-aware retrieval boosts reasoning memory for "why" queries.
- Detail and timeline are explicit follow-up calls; search stays compact.

Primary MCP tools:

- `memorix_search`
- `memorix_detail`
- `memorix_timeline`
- `memorix_store`
- `memorix_store_reasoning`
- `memorix_search_reasoning`
- `memorix_session_start`
- `memorix_session_end`
- `memorix_graph_context`
- `memorix_retention`
- `memorix_transfer`

## Configuration

Memorix uses TOML as the main configuration model:

- global defaults: `~/.memorix/config.toml`
- project overrides: `<git-root>/memorix.toml`

Compatibility inputs for existing installs:

- legacy project `memorix.yml`
- legacy user `~/.memorix/memorix.yml`
- project `.env`
- user `~/.memorix/.env`
- legacy `~/.memorix/config.json`

Those compatibility files are still read, but new docs and setup flows use TOML.

Minimal config:

```toml
[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"
```

Important lanes:

- `[agent]`: memcode's interactive coding model
- `[memory.llm]`: memory formation, summaries, deduplication, optional rerank
- `[embedding]`: semantic/vector search
- `[memory]`: injection and formation behavior
- `[git]`: Git Memory hook and ingest behavior
- `[server]`: server and dashboard defaults

Do not commit credentials. Put credentials in global config or local environment.

## Runtime Modes

### Terminal coding

```bash
memorix
```

Best for users who want a full coding agent in the terminal.

### Agent setup package

```bash
memorix setup --agent <agent> --global
```

Best for connecting Memorix to an existing coding agent or IDE at the user level.

For intentionally repo-local setup only, run it from the target repository without `--global`:

```bash
memorix setup --agent <agent>
```

### Stdio MCP

```bash
memorix serve
```

Best for manual MCP config when the agent setup package is not being used.

### HTTP MCP + dashboard

```bash
memorix background start
```

Best for a shared service, dashboard, Docker, multiple clients, or long-running HTTP workflows.

### Docker

```bash
docker compose up --build -d
```

Docker is for the HTTP service. The container must have access to the repositories it is asked to bind for project-scoped Git and config behavior.

## Supported Clients

Memorix supports Claude Code, Codex, CodeBuddy Code, Cursor, Windsurf, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, DeepSeek Harness, memcode, and other stdio or HTTP MCP clients.

Support depth differs by client:

- `memorix setup --agent <agent> --global` is the default install path.
- MCP is the common integration layer.
- Claude Code, Codex, and GitHub Copilot CLI receive local plugin packages.
- Pi receives a user-level package when setup runs with `--global`; Gemini CLI receives a local extension package.
- OpenClaw receives a compatible bundle; Hermes Agent receives a plugin package; Oh-my-Pi receives a package/extension entry.
- Project instructions and rules include AGENTS.md, GEMINI.md, Cursor rules, Windsurf rules, Kiro steering, Trae rules, and DeepSeek Harness AGENTS.md.
- Hooks are generated for agents that expose usable hook events.
- OpenCode receives a local plugin file at `.opencode/plugins/memorix.js`, an OpenCode skill at `.opencode/skills/memorix-memory/SKILL.md`, plus `opencode.json` MCP config.
- memcode is the bundled terminal agent and uses the same project memory pool.

## Orchestration Coordination

`memorix orchestrate` is the main entry point for subagent-style coordinated implementation work. The `team`, `task`, `message`, `handoff`, `lock`, and `poll` commands are the coordination state used by orchestration and explicit handoff workflows. You don't need them for ordinary memory search or memcode sessions.

Worktree safety:

- single-worker runs use the current checkout by default
- parallel runs create task worktrees under `.worktrees/`
- `--isolated` forces worktree isolation for one worker
- `--no-worktree` disables worktree isolation
- dirty Git worktrees are rejected unless `--allow-dirty` is set
- successful task worktrees auto-merge unless `--no-auto-merge` is set

Use it when you need:

- task board
- role-based claiming
- handoff messages
- advisory file locks
- orchestrated subagent work

Commands:

```bash
memorix team status
memorix task list
memorix handoff create
memorix poll --agentId <id>
memorix orchestrate --goal "..."
```

## Privacy Boundary

Memorix stores explicit memories, session metadata, Git-derived facts, reasoning traces, and optional hook-captured project knowledge.

Shared memory does not mean raw chat transcripts are mirrored between IDEs.

For handoff debugging:

```bash
memorix receipt --json
memorix doctor --receipt
```

Receipts expose hashes and counts, not raw prompts, memory text, local paths, or tool payloads.

## SDK

```ts
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();
```

Exports:

- `memorix/sdk`: runtime client/server helpers and types
- `memorix/types`: type-only exports
- `memorix`: MCP stdio entry point

## Documentation Index

- README: `README.md`
- Setup: `docs/SETUP.md`
- Configuration: `docs/CONFIGURATION.md`
- Integrations: `docs/INTEGRATIONS.md`
- memcode: `docs/MEMCODE.md`
- API Reference: `docs/API_REFERENCE.md`
- Git Memory: `docs/GIT_MEMORY.md`
- Docker: `docs/DOCKER.md`
- Architecture: `docs/ARCHITECTURE.md`
- Agent Playbook: `docs/AGENT_OPERATOR_PLAYBOOK.md`
- Development: `docs/DEVELOPMENT.md`

## Development

```bash
npm install
npm run lint
npm test
npm run build
```

Requirements:

- Node.js `>=22.18.0`
- npm
- Git
