# 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