memorix

# Memorix

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

Memorix gives coding agents persistent, project-aware memory across sessions, IDEs, terminals, and MCP clients. It stores project knowledge once so multiple agents can retrieve it through plugin packages, MCP, CLI, SDK, generated rules/instructions, hooks, skills, local plugins, or the bundled terminal agent. It works with 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 other MCP-capable agents.

## Entry Points

- `memorix setup --agent <agent> --global` installs the recommended user-level integration package or config.
- `memorix setup --list` lists supported agent entry points.
- `memorix serve` starts the manual stdio MCP server for IDEs and agents.
- `memorix background start` starts the HTTP MCP service and dashboard.
- `memorix memory`, `codegraph`, `knowledge`, `reasoning`, `session`, `team`, `task`, `handoff`, `poll`, `receipt`, `sync`, `media`, `ingest`, and `orchestrate` expose the CLI command set.
- `memorix integrate --agent <agent>` and `memorix hooks install --agent <agent>` are manual/fallback generation commands.
- `memorix` and `memcode` open memcode, the bundled terminal agent that uses the same project memory pool.
- `memorix dashboard` opens the local read-mostly dashboard.
- `memorix setup --agent grok --global` installs Grok's native lifecycle hooks and `AGENTS.md` guidance; Grok keeps MCP configuration under its own control.
- `memorix sync store status|push|pull` is an opt-in project-scoped event relay; it never uploads the live SQLite database or WAL files.

## Memory Model

Memorix combines durable memory with a bounded task Workset:

- **Observation Memory**: facts, gotchas, fixes, implementation notes, what changed
- **Reasoning Memory**: why decisions were made, alternatives, constraints, risks
- **Git Memory**: commit-derived engineering facts with source provenance
- **Code State**: versioned local file/symbol/import facts and freshness links that keep memory tied to the current checkout
- **Claim Ledger and Knowledge Workspace**: source-backed claims compiled into reviewable Markdown proposals, never silent overwrites
- **Canonical Workflows**: project workflows with safe per-agent adapters and recorded verification outcomes
- **Curated Long-Term Memory**: source-bound episodic, semantic, and procedural records that stay candidates until explicitly qualified or approved; only deliberately created `user + portable` records can be reused across projects on the same local installation. Keyword retrieval stays primary; optional cross-language/paraphrase fallback is bounded to 1.8 seconds and never blocks lexical delivery.

For non-trivial coding work, agents normally call `memorix_project_context` (or `memorix context --task "...")`. It selects a small task Workset with current facts, relevant evidence, start files, cautions, and verification hints instead of dumping all old text memory. Search is project-scoped by default. Use global scope only when cross-project recall is intentional.

The built-in CodeGraph Lite index is structural and intentionally not presented as a complete semantic graph. A project that already has a healthy local CodeGraph index can contribute a small validated semantic outline through `[codegraph].external_context = "auto"`; Memorix never initializes, syncs, exports, or remotely uploads that index.

## memcode

memcode is the terminal coding agent bundled with Memorix. It reads from and writes to the same project memory pool used by MCP-connected coding agents.

Common commands:

```bash
memorix
memcode
memcode -p "summarize this repo"
memcode -c
memcode -r
```

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

## Configuration

Memorix uses TOML as the user-facing configuration model:

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

Core lanes:

- `[memory.llm]` for memory formation, summaries, deduplication, optional rerank
- `[embedding]` for semantic/vector search
- `[memory]` for injection and formation behavior
- `[agent]` for the model memcode talks to while coding

Legacy `memorix.yml`, `.env`, and `~/.memorix/config.json` are still read for compatibility, but new setups should use TOML.

## Quick Setup

```bash
npm install -g memorix
memorix init --global
memorix setup --agent claude --global
```

Generic MCP client config:

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

Manual stdio MCP:

```bash
memorix serve
```

For HTTP MCP:

```bash
memorix background start
```

Endpoint: `http://localhost:3211/mcp`.

## Core Links

- GitHub: https://github.com/AVIDS2/memorix
- npm: https://www.npmjs.com/package/memorix
- README: https://github.com/AVIDS2/memorix/blob/main/README.md
- Setup: https://github.com/AVIDS2/memorix/blob/main/docs/SETUP.md
- Configuration: https://github.com/AVIDS2/memorix/blob/main/docs/CONFIGURATION.md
- API Reference: https://github.com/AVIDS2/memorix/blob/main/docs/API_REFERENCE.md
- Integration Surfaces: https://github.com/AVIDS2/memorix/blob/main/docs/INTEGRATIONS.md
- Git Memory: https://github.com/AVIDS2/memorix/blob/main/docs/GIT_MEMORY.md
- memcode: https://github.com/AVIDS2/memorix/blob/main/docs/MEMCODE.md
- Agent Playbook: https://github.com/AVIDS2/memorix/blob/main/docs/AGENT_OPERATOR_PLAYBOOK.md
- Long-Term Memory Architecture: https://github.com/AVIDS2/memorix/blob/main/docs/1.3-MEMORY-ARCHITECTURE.md
- Full AI context: https://github.com/AVIDS2/memorix/blob/main/llms-full.txt