llms-full.txt

# 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, Cursor, Windsurf, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, 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.3 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.
- Windsurf, Kiro, Antigravity, Trae: MCP config plus rules/hooks where supported.

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

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
- 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, Cursor, Windsurf, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, 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, and Trae rules.
- 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.19.0`
- npm
- Git