memorix 1.0.4 → 1.0.6

package/CLAUDE.md

@@ -1,56 +1,106 @@
-# Memorix — Agent Instructions for Claude Code
-
-You have access to Memorix, a cross-agent memory system. Use it to persist and recall project knowledge across sessions.
-
-## When to SEARCH memory (memorix_search)
-
-- **Session start**: Always search for recent context at the beginning of a conversation
-- **Before making decisions**: Search for past decisions on the same topic
-- **When the user asks "remember"/"what did we"/"last time"**: Search for relevant history
-- **Before implementing features**: Check if similar work was done before
-- **When encountering errors**: Search for known gotchas and past solutions
-
-## When to STORE memory (memorix_store)
-
-- **Architecture decisions**: Why you chose X over Y (type: `decision`)
-- **Bug fixes**: Root cause and solution (type: `problem-solution`)
-- **Gotchas/pitfalls**: Things that tripped you up (type: `gotcha`)
-- **How things work**: Non-obvious system behavior (type: `how-it-works`)
-- **Changes made**: Significant code changes (type: `what-changed`)
-- **Trade-offs**: Compromises and their reasoning (type: `trade-off`)
-- **Session goals**: What the user asked for at session start (type: `session-request`)
-
-## When to check RETENTION (memorix_retention)
-
-- Periodically check which memories are stale or candidates for archiving
-- Review top-relevant memories to avoid duplicating past work
-
-## Best Practices
-
-1. **Be specific in titles**: "Fixed Docker timeout from 30s to 60s" not "Fixed bug"
-2. **Include facts**: Structured data like "Default port: 3001", "Retry count: 3"
-3. **Tag files**: Always include filesModified when you edit files
-4. **Use concepts**: Add searchable keywords for future retrieval
-5. **Don't over-store**: Only store knowledge that would be useful in a future session
-6. **Entity naming**: Use kebab-case descriptive names like "auth-module", "docker-config"
-
-## Tool Quick Reference
-
-| Tool | When | Example |
-|------|------|---------|
-| `memorix_search` | Find past knowledge | `query: "authentication"` |
-| `memorix_store` | Save new knowledge | `type: "decision", title: "Use JWT for auth"` |
-| `memorix_detail` | Get full observation | `ids: [42, 43]` |
-| `memorix_timeline` | See what happened around an event | `anchorId: 42` |
-| `memorix_resolve` | Mark task done / bug fixed | `ids: [42]` |
-| `memorix_session_start` | Load context at session start | (no params needed) |
-| `memorix_session_end` | Save session summary | `summary: "## Goal\n..."` |
-| `memorix_promote` | Make observation permanent | `action: "promote", observationIds: [42]` |
-| `memorix_retention` | Check memory health | `action: "report"` |
-| `memorix_transfer` | Export/import memories | `action: "export"` |
-| `memorix_rules_sync` | Sync agent rules | `action: "status"` |
-| `memorix_workspace_sync` | Migrate workspace configs | `action: "scan"` |
-| `team_manage` | Register agent | `action: "join", name: "claude-backend"` |
-| `team_file_lock` | Lock file before editing | `action: "lock", file: "src/auth.ts"` |
-| `team_task` | Create/claim tasks | `action: "create", description: "Fix auth bug"` |
-| `team_message` | Send message to other agent | `action: "send", to: "agent-id"` |
+# Memorix - Agent Instructions for Claude Code
+
+You have access to Memorix, an open-source cross-agent memory layer for coding agents via MCP. Use it to persist and recall project knowledge across sessions, preserve reasoning, and retrieve Git-backed engineering truth when relevant.
+
+## Rule 1: Bind the project, then start with context
+
+At the beginning of every conversation:
+
+1. Call `memorix_session_start` to load the previous session summary and recent high-value context.
+2. If you are connected to the HTTP control-plane mode (normally started with `memorix background start`; `memorix serve-http` is the foreground variant) and you know the current workspace path, pass:
+   - `agent`
+   - `projectRoot` = the absolute path of the current workspace or repo root
+3. If you are using stdio / Quick Mode and Memorix is already project-bound, calling `memorix_session_start` without `projectRoot` is acceptable.
+4. If session start fails because the project could not be resolved, retry with the correct absolute workspace path instead of continuing with project-scoped memory calls.
+5. Then call `memorix_search` with a query related to the user's first message or the current project.
+6. If results matter, use `memorix_detail` to inspect the most relevant memories.
+7. If the user is asking about "what changed", prioritize Git-backed memories when relevant.
+
+Important:
+
+- `projectRoot` is a detection anchor only; Git remains the source of truth for project identity.
+- In HTTP control-plane mode, explicit `projectRoot` binding is the safest way to avoid cross-project drift.
+
+## Rule 2: Store meaningful knowledge, not noise
+
+Use `memorix_store` when you learn something a future agent should not have to rediscover.
+
+Store:
+
+- architecture or design decisions -> `decision`
+- bug root cause + fix -> `problem-solution`
+- non-obvious pitfalls -> `gotcha`
+- implementation explanations -> `how-it-works`
+- significant code or config changes -> `what-changed`
+- trade-offs and rationale -> `trade-off`
+- session handoff summaries -> `session-request`
+
+Do not store:
+
+- greetings
+- simple file reads
+- trivial shell commands
+- redundant status chatter
+
+## Rule 3: Preserve reasoning
+
+When the important value is **why**, use `memorix_store_reasoning`:
+
+- alternatives considered
+- rationale
+- constraints
+- expected outcome
+- risks
+
+Reasoning memories are especially useful for future "why did we choose this?" questions.
+
+## Rule 4: Resolve completed work
+
+When a task is done or a bug is fixed, call `memorix_resolve`.
+
+This keeps default search focused on active memory instead of resurfacing already-finished work forever.
+
+## Rule 5: Respect project boundaries
+
+- Default search is current-project scoped.
+- Use global search only when the task is explicitly cross-project.
+- If a global result comes from another project, open it with project-aware refs when needed.
+
+## Rule 6: Favor structured, reusable memory
+
+Best practices:
+
+1. Use specific titles.
+2. Include structured facts.
+3. Include `filesModified` when you touched code.
+4. Include concepts for searchability.
+5. Prefer concise reusable summaries over raw transcripts.
+6. Store milestones such as releases, published versions, and important merges.
+
+## Tool Guide
+
+### Core retrieval
+
+- `memorix_session_start` - load session context; in HTTP mode, prefer passing `projectRoot`
+- `memorix_search` - search current or global memory
+- `memorix_detail` - read full memory details
+- `memorix_timeline` - inspect chronological context
+
+### Core storage
+
+- `memorix_store` - store reusable project knowledge
+- `memorix_store_reasoning` - store design reasoning and trade-offs
+- `memorix_resolve` - mark completed memories resolved
+
+### Quality and operations
+
+- `memorix_retention` - inspect decay/archive state
+- `memorix_promote` - turn important observations into mini-skills
+- `memorix_skills` - generate or inspect project skills
+- `memorix_transfer` - export/import project memory
+
+### Collaboration and platform
+
+- `memorix_rules_sync` - inspect or sync rules across agents
+- `memorix_workspace_sync` - inspect or migrate workspace integrations
+- `team_manage`, `team_file_lock`, `team_task`, `team_message` - HTTP collaboration layer

package/README.md

@@ -5,8 +5,8 @@
 <h1 align="center">Memorix</h1>
 
 <p align="center">
-  <strong>Local-first memory platform for AI coding agents.</strong><br>
-  Git truth, reasoning memory, and cross-agent recall in one MCP server.
+  <strong>Open-source cross-agent memory layer for coding agents.</strong><br>
+  Compatible with Cursor, Claude Code, Codex, Windsurf, Gemini CLI, GitHub Copilot, Kiro, OpenCode, Antigravity, and Trae through MCP.
 </p>
 
 <p align="center">
@@ -18,30 +18,63 @@
 </p>
 
 <p align="center">
-  <strong>Git Memory</strong> · <strong>Reasoning Memory</strong> · <strong>Cross-Agent Recall</strong> · <strong>Control Plane Dashboard</strong>
+  <strong>Git Memory</strong> | <strong>Reasoning Memory</strong> | <strong>Cross-Agent Recall</strong> | <strong>Control Plane Dashboard</strong>
 </p>
 
 <p align="center">
-  <a href="README.zh-CN.md">中文文档</a> ·
-  <a href="#quick-start">Quick Start</a> ·
-  <a href="#how-it-works">How It Works</a> ·
-  <a href="#documentation">Documentation</a> ·
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="#quick-start">Quick Start</a> |
+  <a href="#supported-clients">Supported Clients</a> |
+  <a href="#core-workflows">Core Workflows</a> |
+  <a href="#documentation">Documentation</a> |
   <a href="docs/SETUP.md">Setup Guide</a>
 </p>
 
 ---
 
+## For Coding Agents
+
+If you are using an AI coding agent to install or operate Memorix, have it read the [Agent Operator Playbook](docs/AGENT_OPERATOR_PLAYBOOK.md) first.
+
+That playbook is the canonical AI-facing guide for:
+
+- installation and runtime-mode selection
+- Git/project binding rules
+- stdio vs HTTP control-plane setup
+- per-agent integration and hooks
+- generated dot-directory behavior
+- troubleshooting and safe operating rules
+
 ## Why Memorix
 
-Most AI coding agents remember only the current thread. Memorix gives them a shared, persistent memory layer across IDEs, sessions, and projects.
+Most coding agents remember only the current thread. Memorix gives them a shared, persistent memory layer across IDEs, sessions, and projects.
 
 What makes Memorix different:
 
 - **Git Memory**: turn `git commit` into searchable engineering memory with noise filtering and commit provenance.
 - **Reasoning Memory**: store why a decision was made, not just what changed.
-- **Cross-Agent Local Recall**: Cursor, Windsurf, Claude Code, Codex, Copilot, Kiro, OpenCode, Gemini CLI, and more can read the same local memory base.
+- **Cross-Agent Local Recall**: multiple IDEs and agents can read the same local memory base instead of living in isolated silos.
 - **Memory Quality Pipeline**: formation, compaction, retention, and source-aware retrieval work together instead of acting like isolated tools.
 
+Memorix is built for one job: let multiple coding agents share the same durable project memory through MCP without giving up Git truth, reasoning history, or local control.
+
+## Supported Clients
+
+Memorix currently ships first-class integrations for:
+
+- Cursor
+- Claude Code
+- Codex
+- Windsurf
+- Gemini CLI
+- GitHub Copilot
+- Kiro
+- OpenCode
+- Antigravity
+- Trae
+
+If a client can speak MCP and launch a local command or HTTP endpoint, it can usually connect to Memorix even if it is not in the list above yet.
+
 ---
 
 ## Quick Start
@@ -52,35 +85,92 @@ Install globally:
 npm install -g memorix
 ```
 
-Initialize project config:
+Initialize Memorix config:
 
 ```bash
 memorix init
 ```
 
+`memorix init` lets you choose between `Global defaults` and `Project config`.
+
 Memorix uses two files with two roles:
 
 - `memorix.yml` for behavior and project settings
 - `.env` for secrets such as API keys
 
-Choose one runtime mode:
+Then pick the path that matches what you want to do:
+
+| You want | Run | Best for |
+| --- | --- | --- |
+| Quick MCP setup inside one IDE | `memorix serve` | Cursor, Claude Code, Codex, Windsurf, Gemini CLI, and other stdio MCP clients |
+| Dashboard + long-lived HTTP MCP in the background | `memorix background start` | Daily use, multiple agents, collaboration, dashboard |
+| Foreground HTTP mode for debugging or a custom port | `memorix serve-http --port 3211` | Manual supervision, debugging, custom launch control |
+
+Most users should choose **one** of the first two options:
+
+- `memorix serve` if you just want Memorix available inside your IDE as fast as possible
+- `memorix background start` if you want the dashboard and a shared HTTP control plane running in the background
+
+Optional local UI:
 
 ```bash
-memorix serve
+memorix
 ```
 
-Use `serve` for normal stdio MCP integrations.
+Use bare `memorix` only when you want the interactive local workbench in a TTY. It is not the main setup path for most users.
+
+Companion commands:
+
+```bash
+memorix background status
+memorix background logs
+memorix background stop
+```
+
+If you need the HTTP control plane in the foreground for debugging, manual supervision, or a custom port, use:
 
 ```bash
 memorix serve-http --port 3211
 ```
 
-Use `serve-http` when you want the HTTP transport, collaboration features, and the dashboard on the same port.
+If you are using the HTTP control plane across multiple workspaces or agents, make sure each session binds with `memorix_session_start(projectRoot=...)`.
+
+The deeper details around startup root selection, project binding, config precedence, and agent/operator workflows live in [docs/SETUP.md](docs/SETUP.md) and the [Agent Operator Playbook](docs/AGENT_OPERATOR_PLAYBOOK.md).
 
 Add Memorix to your MCP client:
 
+### Generic stdio MCP config
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### Generic HTTP MCP config
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "transport": "http",
+      "url": "http://localhost:3211/mcp"
+    }
+  }
+}
+```
+
+If you use the HTTP control plane across multiple workspaces or agents, the client or agent should also call `memorix_session_start(projectRoot=ABSOLUTE_WORKSPACE_PATH)` at the beginning of each project session.
+
+The per-client examples below show the simplest stdio shape. If you prefer the shared HTTP control plane, keep the generic HTTP block above and use the client-specific variants in [docs/SETUP.md](docs/SETUP.md).
+
 <details open>
-<summary><strong>Cursor</strong> · <code>.cursor/mcp.json</code></summary>
+<summary><strong>Cursor</strong> | <code>.cursor/mcp.json</code></summary>
 
 ```json
 {
@@ -103,7 +193,7 @@ claude mcp add memorix -- memorix serve
 </details>
 
 <details>
-<summary><strong>Codex</strong> · <code>~/.codex/config.toml</code></summary>
+<summary><strong>Codex</strong> | <code>~/.codex/config.toml</code></summary>
 
 ```toml
 [mcp_servers.memorix]
@@ -150,7 +240,7 @@ Git memories are stored with `source='git'`, commit hashes, changed files, and n
 ### 3. Run the control plane
 
 ```bash
-memorix serve-http --port 3211
+memorix background start
 ```
 
 Then open:
@@ -158,20 +248,96 @@ Then open:
 - MCP HTTP endpoint: `http://localhost:3211/mcp`
 - Dashboard: `http://localhost:3211`
 
-This mode gives you collaboration tools, project identity diagnostics, config provenance, Git Memory views, and the dashboard in one place.
+Companion commands:
+
+```bash
+memorix background status
+memorix background logs
+memorix background stop
+```
+
+Use `background start` as the default long-lived HTTP mode. If you need to keep the control plane in the foreground for debugging or manual supervision, use:
+
+```bash
+memorix serve-http --port 3211
+```
+
+This HTTP mode gives you collaboration tools, project identity diagnostics, config provenance, Git Memory views, and the dashboard in one place.
+
+When multiple HTTP sessions are open at once, each session should bind itself with `memorix_session_start(projectRoot=...)` before using project-scoped memory tools.
 
 ---
 
 ## How It Works
 
 ```mermaid
-graph TB
-    A["git commit / agent tool call / manual store"] --> B["Memorix Runtime"]
-    B --> C["Observation / Reasoning / Git Memory"]
-    C --> D["Formation + Indexing + Graph + Retention"]
-    D --> E["Search / Detail / Timeline / Dashboard / Team"]
+flowchart LR
+    subgraph Ingress["Ingress Surfaces"]
+        A1["Git hooks / ingest"]
+        A2["MCP tools"]
+        A3["CLI / TUI"]
+        A4["HTTP dashboard"]
+    end
+
+    subgraph Runtime["Memorix Runtime"]
+        B1["stdio MCP server"]
+        B2["HTTP control plane"]
+        B3["project binding + config"]
+    end
+
+    subgraph Memory["Memory Substrates"]
+        C1["Observation memory"]
+        C2["Reasoning memory"]
+        C3["Git memory"]
+        C4["Session + team state"]
+    end
+
+    subgraph Processing["Async Processing"]
+        D1["Formation pipeline"]
+        D2["Embedding + indexing"]
+        D3["Graph linking"]
+        D4["Dedup + retention"]
+    end
+
+    subgraph Consumption["Consumption Surfaces"]
+        E1["Search / detail / timeline"]
+        E2["Dashboard / team views"]
+        E3["Agent recall / handoff"]
+    end
+
+    A1 --> B1
+    A2 --> B1
+    A2 --> B2
+    A3 --> B1
+    A3 --> B2
+    A4 --> B2
+
+    B1 --> B3
+    B2 --> B3
+
+    B3 --> C1
+    B3 --> C2
+    B3 --> C3
+    B3 --> C4
+
+    C1 --> D1
+    C1 --> D2
+    C1 --> D3
+    C1 --> D4
+    C2 --> D1
+    C2 --> D3
+    C3 --> D2
+    C4 --> D3
+
+    D1 --> E1
+    D2 --> E1
+    D3 --> E2
+    D4 --> E3
+    C4 --> E3
 ```
 
+Memorix is not a single linear pipeline. It accepts memory from multiple ingress surfaces, persists it across multiple substrates, runs several asynchronous quality/indexing branches, and exposes the results through different retrieval and collaboration surfaces.
+
 ### Memory Layers
 
 - **Observation Memory**: what changed, how something works, gotchas, problem-solution notes
@@ -183,7 +349,7 @@ graph TB
 - Default search is **project-scoped**
 - `scope="global"` searches across projects
 - Global hits can be opened explicitly with project-aware refs
-- Source-aware retrieval boosts Git memories for “what changed” questions and reasoning memories for “why” questions
+- Source-aware retrieval boosts Git memories for "what changed" questions and reasoning memories for "why" questions
 
 ---
 
@@ -213,6 +379,8 @@ graph TB
 
 ### AI-Facing Project Docs
 
+- [Agent Operator Playbook](docs/AGENT_OPERATOR_PLAYBOOK.md)
+- [AI Context Note](docs/AI_CONTEXT.md)
 - [`llms.txt`](llms.txt)
 - [`llms-full.txt`](llms-full.txt)
 
@@ -235,6 +403,7 @@ Key local commands:
 ```bash
 memorix status
 memorix dashboard
+memorix background start
 memorix serve-http --port 3211
 memorix git-hook --force
 ```