memorix 1.0.7 → 1.0.8

package/docs/AGENT_OPERATOR_PLAYBOOK.md

@@ -0,0 +1,684 @@
+# Memorix Agent Operator Playbook
+
+> Primary operating guide for coding agents that need to install, configure, bind, and use Memorix correctly.
+
+This document is written for AI coding agents, not for human-first browsing. If you are an agent helping a user adopt Memorix, use this file as the execution guide before you attempt installation, integration, or troubleshooting.
+
+---
+
+## 1. What Memorix Is
+
+Memorix is an open-source cross-agent memory layer for coding agents via MCP.
+
+It is designed for software work, not generic chat memory. Its core value is that multiple coding agents and IDEs can share:
+
+- **Observation Memory**: what changed, how something works, gotchas, problem-solution notes
+- **Reasoning Memory**: why a decision was made, alternatives, trade-offs, risks
+- **Git Memory**: structured engineering truth derived from commits
+
+It supports:
+
+- stdio MCP (`memorix serve`)
+- HTTP control plane + dashboard (`memorix background start` or `memorix serve-http --port 3211`)
+- local-first project-scoped memory
+- cross-agent recall across Cursor, Claude Code, Codex, Windsurf, Gemini CLI, GitHub Copilot, Kiro, OpenCode, Antigravity, and Trae
+
+### 1.0.8 operator delta
+
+If you used Memorix before `1.0.8`, the operator-visible changes worth knowing are:
+
+- session, search, detail, and timeline now expose a clearer `L1 / L2 / L3` retrieval model
+- compact evidence surfaces better distinguish repository-backed signals, synthesized analysis, and citation-lite support
+- retrieval is more task-line aware inside a single repo and less likely to surface the wrong subdomain
+- obvious credentials are sanitized on write and redacted on retrieval surfaces
+- retention, stale review, audit, and resolve now form a clearer cleanup/remediation loop
+- OpenCode compaction guidance now preserves structured continuation context without falsely implying automatic MCP tool calls
+- `memorix_session_start` is now **lightweight by default**: it binds the project, opens the session, and restores context without auto-registering a team identity
+- team participation is now explicit: use `joinTeam: true` on `memorix_session_start` or call `team_manage(join)` directly
+- Memorix is now **CLI-first for operators**: every Memorix-native operator capability has a terminal route, while MCP remains the integration protocol for IDEs and agents
+- Agent Team page is an **autonomous CLI agents status surface** (not an org backend or IDE-window chat room): shows explicitly joined autonomous agents, open tasks, handoffs, and a "Continue This Project" resume area
+- Docker now has an official HTTP control-plane deployment path; when running in a container, `projectRoot` must be visible inside that container or project-scoped semantics will fail closed
+
+---
+
+## 2. Operating Principles You Must Respect
+
+### CLI is the primary operator surface; MCP is the integration layer
+
+For human operators, prefer `memorix ...` commands first. In 1.0.8, the CLI covers all Memorix-native operator capabilities across session, memory, reasoning, retention, formation, audit, transfer, skills, team, task, message, lock, handoff, poll, sync, and ingest workflows.
+
+Do not ask memory-only users to join the Agent Team. A lightweight session is enough for memory, retrieval, reasoning, and continuation. Join only for explicit task/message/lock coordination or for autonomous CLI-agent work managed by `memorix orchestrate`.
+
+Use MCP when:
+
+- an IDE or agent needs tool calls
+- you are integrating Memorix into an MCP-capable client
+- you need the optional graph-compatibility tools that intentionally remain MCP-only
+
+Use the CLI when:
+
+- a human is operating Memorix directly
+- you are on SSH / Docker / CI / NAS and want direct control
+- you want readable, stable command namespaces instead of raw tool payloads
+
+### Git is the source of truth for project identity
+
+Memorix is project-scoped by default.
+
+Important:
+
+- `projectRoot` is a **detection anchor**
+- Git identity is the **final project identity**
+
+If the workspace is not a Git repository:
+
+- project-safe memory will not bind correctly
+- some commands may fail closed
+- the right first step is usually:
+
+```bash
+git init
+```
+
+Do not assume a plain folder path is enough.
+
+### Choose one runtime model intentionally
+
+There are four practical operator entry points:
+
+- `memorix` for the interactive local workbench in a TTY
+- `memorix serve` for stdio MCP hosts
+- `memorix background start` for an optional long-lived HTTP control plane
+- `memorix serve-http --port 3211` for foreground HTTP control-plane work
+
+The two server runtime modes are:
+
+Use:
+
+```bash
+memorix serve
+```
+
+when the MCP host launches Memorix directly from the current workspace and stdio transport is enough.
+
+Prefer:
+
+```bash
+memorix background start
+```
+
+when the user wants:
+
+- HTTP MCP transport
+- dashboard
+- multiple agents or sessions
+- team/task/message features
+- one shared control-plane process
+
+Default recommendation: if the user just wants memory inside one IDE or terminal, start with `memorix` or `memorix serve`. Reach for HTTP only when a shared background service, multi-client MCP access, or a live dashboard endpoint is actually needed.
+
+Use:
+
+```bash
+memorix serve-http --port 3211
+```
+
+when the user wants the same HTTP control plane in the foreground for debugging, manual supervision, or a custom port.
+
+### In HTTP mode, always bind the project explicitly
+
+At the beginning of a new project session, call:
+
+```json
+{
+  "agent": "your-agent-name",
+  "projectRoot": "ABSOLUTE_WORKSPACE_PATH"
+}
+```
+
+through `memorix_session_start`.
+
+Do not assume the HTTP connection alone tells Memorix which project the user means.
+
+The HTTP control plane is normally started with `memorix background start`; the same project-binding rules apply when you run `memorix serve-http --port 3211` in the foreground.
+
+HTTP MCP sessions idle out after 30 minutes by default. If the user's HTTP MCP client is sensitive to stale session IDs after long idle periods, set `MEMORIX_SESSION_TIMEOUT_MS` before starting or restarting the control plane. Example: `MEMORIX_SESSION_TIMEOUT_MS=86400000` keeps sessions alive for 24 hours.
+
+### Do not confuse project config and global config
+
+Memorix intentionally supports both:
+
+- **project-level** settings and integrations
+- **global-level** defaults
+
+Your job as an agent is to choose the smallest scope that matches the user's goal.
+
+---
+
+## 3. Fastest Valid Setup
+
+Use this path when the user wants the quickest possible adoption.
+
+### Step 1. Install Memorix
+
+```bash
+npm install -g memorix
+```
+
+### Step 2. Ensure the workspace is a Git repo
+
+If not:
+
+```bash
+git init
+```
+
+### Step 3. Initialize config
+
+```bash
+memorix init
+```
+
+`memorix init` is a scope selector, not just a project-local generator. It lets the user choose between:
+
+- `Global defaults`
+- `Project config`
+
+Memorix uses:
+
+- `memorix.yml` for behavior and project settings
+- `.env` for secrets such as API keys
+
+### Step 4. Start stdio MCP mode
+
+If the user wants the local interactive workbench first, they can also run:
+
+```bash
+memorix
+```
+
+Use that for local browsing, commands, and quick validation in a TTY.
+
+Inside the TUI workbench, slash commands are available: `/chat` (or just type a question), `/search`, `/remember`, `/recent`, `/resume` (or `/resume 2` for thread #2), `/new`, `/clear`, `/doctor`, `/project`, `/background`, `/dashboard`, `/integrate`, `/configure`, `/cleanup`, `/ingest`, `/help`, `/exit`. Most have short aliases (e.g. `/s`, `/r`, `/v`, `/d`, `/q`).
+
+```bash
+memorix serve
+```
+
+### Step 5. Add MCP config to the target client
+
+Generic stdio MCP example:
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+Generic HTTP MCP example:
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "transport": "http",
+      "url": "http://localhost:3211/mcp"
+    }
+  }
+}
+```
+
+**⚠ serverUrl mode requires the background control plane to already be running.**
+The `serverUrl` config is a pure HTTP client — it connects to an endpoint but does NOT start the server.
+If the control plane is down, the MCP client receives `ECONNREFUSED` with no auto-recovery.
+
+To guarantee the server is available before the IDE connects, use:
+
+```bash
+memorix background ensure
+```
+
+This command checks health and auto-starts if needed. Add it to your shell profile or IDE startup script.
+
+Some IDEs (Windsurf, Cursor) use `serverUrl` in their MCP config and do not support preflight commands.
+For those, the background must be started manually or via OS startup (see §4 Step 3b below).
+
+If you choose HTTP mode, do not stop at the URL. The agent must also bind each project session with `memorix_session_start(projectRoot=ABSOLUTE_WORKSPACE_PATH)` when the workspace path is available.
+
+This is the best path for:
+
+- one workspace
+- one agent/IDE
+- quick validation
+- minimal moving parts
+
+---
+
+## 4. Full Control-Plane Setup
+
+Use this path when the user wants the full Memorix product model.
+
+### Step 1. Install and initialize
+
+```bash
+npm install -g memorix
+memorix init
+```
+
+### Step 2. Ensure Git identity exists
+
+If needed:
+
+```bash
+git init
+```
+
+### Step 3. Start HTTP control plane
+
+```bash
+memorix background start
+```
+
+Main URLs:
+
+- MCP endpoint: `http://localhost:3211/mcp`
+- dashboard: `http://localhost:3211`
+
+Companion commands:
+
+```bash
+memorix background status   # Show running state and health
+memorix background ensure   # Auto-start if not running (idempotent, silent when healthy)
+memorix background logs     # Show recent log output
+memorix background stop     # Stop the background control plane
+memorix background restart  # Stop + start
+```
+
+### Step 3b. Make the control plane persistent (recommended)
+
+`memorix background start` spawns a detached process that survives the terminal, but it does **not** survive system reboots or user logouts.
+
+The background control plane is a **persistent server** — it is designed to run continuously in the background, not to be auto-launched by MCP clients on demand.
+
+To make it truly persistent:
+
+**Windows** — add to shell profile (`$PROFILE`):
+
+```powershell
+memorix background ensure
+```
+
+**macOS/Linux** — add to shell profile (`.bashrc`, `.zshrc`):
+
+```bash
+memorix background ensure 2>/dev/null
+```
+
+Or use a launchd plist / systemd user service for true boot-time persistence.
+
+**Why this matters:** IDEs that use `serverUrl` (Windsurf, Cursor HTTP mode) connect to `http://localhost:3211/mcp` but cannot start the server. If the control plane is down, the IDE shows an MCP error with no recovery path. The user must run `memorix background start` or `ensure` manually.
+
+At startup, `serve-http` seeds its default project root from:
+
+1. `--cwd`
+2. `MEMORIX_PROJECT_ROOT`
+3. `~/.memorix/last-project-root`
+4. `process.cwd()`
+
+That startup root is useful for dashboard and server boot, but it does not replace explicit session binding.
+
+### Step 4. Bind each HTTP session explicitly
+
+At session start, call:
+
+```json
+{
+  "agent": "your-agent-name",
+  "projectRoot": "ABSOLUTE_WORKSPACE_PATH"
+}
+```
+
+through `memorix_session_start`.
+
+This is the right path for:
+
+- dashboard users
+- multi-agent workflows
+- team/task/message usage
+- multiple concurrent sessions
+- debugging project binding and config provenance
+
+---
+
+## 5. Agent Decision Tree
+
+Use this routing logic when helping a user.
+
+### If the user says:
+
+- "I just want it working quickly"
+- "I only need Cursor / Claude Code / Codex"
+- "I don't care about dashboard"
+
+Choose:
+
+- `memorix serve`
+- simple stdio MCP config
+
+### If the user says:
+
+- "I want dashboard"
+- "I want HTTP MCP"
+- "I want multiple agents / IDEs at once"
+- "I want shared HTTP MCP or a live dashboard endpoint"
+
+Choose:
+
+- `memorix background start`
+- explicit `memorix_session_start(projectRoot=...)`
+
+### If the user asks for IDE integration files
+
+Use:
+
+```bash
+memorix integrate --agent <agent>
+```
+
+This is explicit, opt-in generation.
+
+### If the user asks for hooks
+
+Use:
+
+```bash
+memorix hooks install --agent <agent>
+```
+
+This is also explicit and opt-in.
+
+Do not assume the user wants every supported IDE directory generated.
+
+---
+
+## 6. Generated Dot Directories: What They Mean
+
+Memorix now favors **explicit, per-agent installation**.
+
+That means:
+
+- it does **not** need to spray every supported `.xxx` directory into every repo
+- the user or agent can select only the integrations they actually need
+
+Important:
+
+- many `.cursor`, `.windsurf`, `.claude`, `.gemini`, `.opencode`, etc. directories are not arbitrary clutter
+- they are often part of the target IDE's own discovery protocol
+- do **not** promise that all of them can be physically merged into one folder without breaking host detection
+
+What you can say safely:
+
+- Memorix supports **on-demand generation**
+- it does **not** require generating every integration at once
+- different hosts still expect their own directory or config path
+
+---
+
+## 7. Hooks vs Integrations
+
+Do not confuse these.
+
+### `memorix integrate`
+
+Purpose:
+
+- generate IDE/agent integration files
+- write MCP config, rules, settings, or plugin files for a specific target
+
+Typical use:
+
+```bash
+memorix integrate --agent cursor
+memorix integrate --agent opencode
+memorix integrate --agent gemini-cli
+```
+
+### `memorix hooks install`
+
+Purpose:
+
+- install auto-capture hooks for supported agents
+
+Typical use:
+
+```bash
+memorix hooks install --agent cursor
+memorix hooks install --agent opencode
+```
+
+### `memorix git-hook`
+
+Purpose:
+
+- install a post-commit hook in the current Git repo
+- automatically ingest commits as Git Memory
+
+Typical use:
+
+```bash
+memorix git-hook --force
+```
+
+---
+
+## 8. What an Agent Should Do at Session Start
+
+In HTTP control-plane mode:
+
+1. Call `memorix_session_start`
+2. Pass:
+   - `agent` — display name (e.g. `"cursor-frontend"`)
+   - `agentType` — optional agent type for Agent Team role mapping (e.g. `"windsurf"`, `"cursor"`, `"claude-code"`, `"codex"`, `"gemini-cli"`)
+   - `projectRoot` = absolute workspace path
+3. By default this only starts a lightweight session. It does **not** auto-register a team identity.
+4. If the user wants autonomous Agent Team features, either:
+   - call `memorix_session_start` with `joinTeam: true`
+   - or call `team_manage(join)` explicitly
+5. If project binding fails, stop using project-scoped tools until the path is corrected
+6. Then use:
+   - `memorix_search`
+   - `memorix_detail`
+   - `memorix_timeline`
+   as needed
+
+In stdio / project-bound mode:
+
+- `projectRoot` is optional if the process is already launched from the correct workspace
+- keep this path lightweight unless the user explicitly asks for team coordination
+
+Important boundary:
+
+- `team_manage(join)` does not make separate Cursor, Windsurf, Codex, or TUI conversation windows magically talk to each other.
+- For real autonomous multi-agent implementation loops, use `memorix orchestrate`; it launches CLI agents, coordinates work through tasks/context, and runs verification/fix/review gates.
+
+---
+
+## 9. Recommended Command Set for Agents
+
+### Core runtime
+
+```bash
+memorix serve
+memorix background start
+memorix serve-http --port 3211
+memorix doctor
+memorix status
+```
+
+### Project setup
+
+```bash
+memorix init
+memorix integrate --agent <agent>
+memorix hooks install --agent <agent>
+memorix git-hook --force
+```
+
+### Memory operations
+
+Use MCP tools:
+
+- `memorix_store`
+- `memorix_search`
+- `memorix_detail`
+- `memorix_timeline`
+- `memorix_resolve`
+- `memorix_deduplicate`
+- `memorix_store_reasoning`
+
+---
+
+## 10. Installation and Troubleshooting Checklist
+
+If Memorix "doesn't work", check these in order.
+
+### 1. Is the workspace a Git repo?
+
+If not, run:
+
+```bash
+git init
+```
+
+### 2. Is the runtime mode correct?
+
+- stdio MCP client -> `memorix serve`
+- HTTP/dashboard/control-plane use case -> `memorix background start` by default, or `memorix serve-http --port 3211` when foreground control is required
+
+### 3. Is the background control plane actually running?
+
+If the MCP client reports `ECONNREFUSED` on `localhost:3211`:
+
+```bash
+memorix background status
+```
+
+If it shows "Not running" or "dead":
+
+```bash
+memorix background ensure
+```
+
+If the client is connected but starts failing after roughly 30 minutes of no Memorix tool use, check for stale HTTP session expiry rather than treating it as project binding failure. Restart the control plane with a longer idle timeout:
+
+```powershell
+$env:MEMORIX_SESSION_TIMEOUT_MS = "86400000"
+memorix background restart
+```
+
+Common causes of the background dying:
+- System reboot or user logout (background is not a system service)
+- Unhandled error in the control plane process (now logged to `~/.memorix/background.log`)
+- Terminal that started it was closed before the process fully detached (rare on Node.js v20+)
+
+The heartbeat file `~/.memorix/background.heartbeat` is updated every 30 seconds while the control plane is alive. If `status` reports a dead process with a recent heartbeat, the control plane crashed — check the log file.
+
+### 4. Is the MCP config pointing to the right command?
+
+On Windows, some hosts behave better with `memorix.cmd` than bare `memorix`.
+
+**serverUrl vs command mode:**
+- `serverUrl` (HTTP) requires the background to already be running — it cannot auto-start
+- `command` (stdio) launches `memorix serve` on demand — no background needed; use `memorix dashboard` for a standalone read-mostly dashboard and CLI/team tools for autonomous agent workflows
+
+If using `serverUrl` and the background keeps disappearing, consider switching to stdio mode as a fallback.
+
+### 5. In HTTP mode, did the session bind with `projectRoot`?
+
+If not, the agent may drift into the wrong project bucket or fail closed.
+
+### 6. Did the user install the integration they actually need?
+
+Use:
+
+```bash
+memorix integrate --agent <agent>
+memorix hooks install --agent <agent>
+```
+
+### 7. Is the generated plugin/hook stale?
+
+OpenCode in particular now supports stale-install detection through:
+
+```bash
+memorix hooks status
+```
+
+If outdated, re-run:
+
+```bash
+memorix hooks install --agent opencode
+```
+
+### 8. Are LLM and embedding secrets configured?
+
+Check:
+
+- project `.env`
+- user `~/.memorix/.env`
+- shell-injected env vars
+
+Use:
+
+```bash
+memorix doctor
+```
+
+to inspect active runtime status.
+
+---
+
+## 11. What Not to Do
+
+Do not:
+
+- treat `projectRoot` as the final project identity
+- assume non-Git folders will behave like stable projects
+- mix up stdio and HTTP guidance in the same answer
+- promise that all `.xxx` integration directories can be physically merged
+- tell users "auto-update is implemented" unless you mean the real wired runtime feature
+- rely on stale generated plugin files when diagnosing current behavior
+- assume `serverUrl` HTTP mode will auto-start the background control plane — it cannot
+- tell users "just restart the IDE" when the fix is `memorix background ensure`
+- promise the background control plane survives reboots without OS-level startup config
+
+---
+
+## 12. When This Document Should Be Read First
+
+If a user asks any of these:
+
+- "Install Memorix for me"
+- "Set up Memorix in Cursor / Claude Code / Codex / Windsurf / OpenCode / Gemini CLI"
+- "Why isn't Memorix binding to my project?"
+- "Why does it fail in this workspace?"
+- "How should I use serve vs serve-http?"
+- "What files will this create?"
+- "Why does my MCP client show ECONNREFUSED / connection refused?"
+- "Why did the background control plane disappear?"
+
+read this document first, then act.
+
+This playbook is the canonical AI-facing operator guide for installation, project binding, integration, hooks, troubleshooting, and safe usage.
+## Docker Note
+
+When Memorix runs in Docker, treat it as an **HTTP control-plane deployment**, not a stdio MCP process.
+
+- Connect IDEs and agents to `http://host:3211/mcp`
+- Use `memorix_session_start(projectRoot=...)` with a path that is visible **inside** the container
+- If the repo is not mounted into the container, project-scoped Git/config semantics will fail closed

package/docs/AI_CONTEXT.md

@@ -0,0 +1,18 @@
+# AI Context Note
+
+This file used to hold AI-oriented project context.
+
+That responsibility now lives in two cleaner places:
+
+- [AGENT_OPERATOR_PLAYBOOK.md](AGENT_OPERATOR_PLAYBOOK.md) for installation, runtime selection, Git/project binding, integration, hooks, and troubleshooting
+- [../llms-full.txt](../llms-full.txt) for the broader AI-facing project overview
+
+If you are a coding agent helping a user operate Memorix, read the playbook first.
+
+Why this file now exists only as a pointer:
+
+- the old AI context document had become redundant
+- the operator playbook is now the canonical execution guide
+- the `llms` documents are the better place for model-facing project summaries
+
+Do not treat this file as the primary source of operating instructions.