memorix 1.0.4 → 1.0.6

package/llms-full.txt

@@ -0,0 +1,365 @@
+# Memorix - Full Documentation for AI Systems
+
+> Open-source cross-agent memory layer for coding agents via MCP
+
+## Overview
+
+Memorix is an open-source MCP server written in TypeScript that provides persistent, project-aware memory for coding agents. It is designed for coding workflows, not generic chat memory, and works across Cursor, Claude Code, Codex, Windsurf, Gemini CLI, GitHub Copilot, Kiro, OpenCode, Antigravity, and Trae through MCP.
+
+If you are an AI coding agent helping a user install or operate Memorix, read [docs/AGENT_OPERATOR_PLAYBOOK.md](https://github.com/AVIDS2/memorix/blob/main/docs/AGENT_OPERATOR_PLAYBOOK.md) before taking action. It is the canonical operator guide for runtime mode selection, Git/project binding, integrations, hooks, and troubleshooting.
+
+Memorix solves four recurring problems in AI-assisted development:
+
+1. **Session amnesia** - the next chat forgets what the previous one learned
+2. **IDE isolation** - memory created in one coding IDE is invisible to another
+3. **Engineering truth loss** - commits record what changed, but not in a form agents can easily recall
+4. **Config and workflow fragmentation** - MCP config, agent rules, and IDE integrations drift apart over time
+
+## Product Model
+
+Memorix is best understood as four layers:
+
+1. **Runtime layer**
+   - MCP server over stdio or HTTP
+   - Project detection
+   - Config loading and project switching
+
+2. **Memory core**
+   - Observations
+   - Sessions
+   - Search index
+   - Retention
+   - Export/import
+   - Knowledge graph relations
+
+3. **Quality layer**
+   - Formation pipeline
+   - Source-aware retrieval
+   - Compaction
+   - Optional LLM quality improvements
+   - Optional local vector search
+
+4. **Platform layer**
+   - Git Memory
+   - Hooks and auto-capture
+   - Rules sync
+   - Workspace sync
+   - Team collaboration
+   - Dashboard
+
+## Memory Layers
+
+### 1. Observation Memory
+
+Observation memory stores reusable project knowledge such as:
+
+- architecture decisions
+- gotchas
+- bug fixes
+- implementation notes
+- discoveries
+- trade-offs
+- what changed
+
+Examples:
+
+- `decision` - chose queue-based ingestion over direct writes
+- `problem-solution` - fixed dashboard width jump by stabilizing scrollbar gutter
+- `gotcha` - npm publish fails from Windows device-style cwd paths
+- `what-changed` - reworked project detection to use git identity consistently
+
+### 2. Reasoning Memory
+
+Reasoning memory stores the **why** behind decisions:
+
+- alternatives considered
+- rationale
+- constraints
+- expected outcomes
+- risks
+
+This is the layer that helps future agents understand why a system was designed a certain way instead of only seeing the final code change.
+
+### 3. Git Memory
+
+Git Memory turns commits into structured memory with provenance:
+
+- `source='git'`
+- commit hash
+- files changed
+- inferred type
+- entity extraction
+- noise filtering
+
+Memorix can:
+
+- install a `post-commit` hook
+- ingest a single commit
+- ingest a commit range or recent history
+- skip low-value commit noise
+- preserve release and milestone commits
+
+This is one of Memorix's main differentiators for coding agents.
+
+## Retrieval Model
+
+Memorix retrieval is intentionally layered:
+
+- **Search** - compact project-scoped or global retrieval
+- **Timeline** - chronological context around an event
+- **Detail** - full observation detail
+- **Dashboard** - visual and operational view
+
+Important retrieval behavior:
+
+- default search is **current-project scoped**
+- `scope="global"` searches across projects
+- global results can be opened explicitly with project-aware refs
+- source-aware retrieval boosts:
+  - Git memory for "what changed" style queries
+  - reasoning/decision memory for "why" style queries
+  - both for debugging/problem-solving style queries
+
+## Configuration Model
+
+Memorix now uses a simple outward-facing model:
+
+- `memorix.yml` for behavior and project settings
+- `.env` for secrets
+
+Internally it still supports layered config and compatibility fallbacks, but the intended user-facing mental model is:
+
+- **behavior in YAML**
+- **secrets in `.env`**
+
+This is more structured than flat env-only config and is intended to keep the system explainable.
+
+## Runtime Modes
+
+### Stdio MCP
+
+```bash
+memorix serve
+```
+
+Use this for normal MCP clients that expect stdio transport.
+
+This is the best fit for quick, single-project usage where the client already launches Memorix from the correct workspace root.
+
+Generic stdio MCP config:
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### HTTP MCP + Dashboard
+
+```bash
+memorix background start
+```
+
+Use this when you want:
+
+- HTTP MCP transport
+- collaboration tools
+- the dashboard on the same port
+- a long-lived control plane that keeps running in the background
+
+Use `memorix serve-http --port 3211` when you want the same HTTP control plane in the foreground for debugging, manual supervision, or a custom port.
+
+Important:
+
+- In HTTP control-plane mode, agents should call `memorix_session_start` with `projectRoot` set to the **absolute path of the current workspace or repo root** when that path is available.
+- `projectRoot` is a detection anchor only; Git remains the source of truth for the final project identity.
+- If the client cannot supply a reliable workspace path, HTTP mode should fail closed instead of silently inventing an `untracked/*` project.
+
+Typical endpoints:
+
+- MCP endpoint: `http://localhost:3211/mcp`
+- Dashboard: `http://localhost:3211`
+
+Generic HTTP MCP config:
+
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "transport": "http",
+      "url": "http://localhost:3211/mcp"
+    }
+  }
+}
+```
+
+## Supported Environments
+
+Memorix is designed for multi-agent and multi-IDE coding workflows. It supports integrations and workflows around:
+
+- Cursor
+- Windsurf
+- Claude Code
+- Codex
+- Copilot / VS Code MCP setups
+- Kiro
+- Antigravity
+- OpenCode
+- Trae
+- Gemini CLI
+
+The exact integration surface differs by IDE, but the shared memory model remains the same.
+
+## Key Capabilities
+
+### Persistent Cross-Session Memory
+
+Agents can search prior work at session start and continue from real project context instead of asking the user to re-explain.
+
+### Cross-Agent Recall
+
+Different coding agents can read from the same local memory base, making handoff and tool switching much smoother.
+
+### Git-Memory Pipeline
+
+Memorix can capture engineering truth from Git and make it searchable as memory instead of raw commit text.
+
+### Reasoning Preservation
+
+Memorix can store design rationale and trade-offs directly, which is critical for avoiding contradictory future suggestions.
+
+### Dashboard / Control Plane
+
+The dashboard exposes:
+
+- memory source distribution
+- Git Memory views
+- config provenance
+- project identity health
+- retention and session summaries
+- graph visualization
+
+### Team Collaboration
+
+When running with HTTP transport, Memorix also supports:
+
+- agent registry
+- advisory file locks
+- task board
+- agent-to-agent messages
+
+## Tool Surface
+
+Memorix exposes MCP tools across several groups:
+
+### Core Memory
+
+- `memorix_store`
+- `memorix_search`
+- `memorix_detail`
+- `memorix_timeline`
+- `memorix_resolve`
+- `memorix_retention`
+- `memorix_transfer`
+
+### Session and Reasoning
+
+- `memorix_session_start`
+- `memorix_session_end`
+- `memorix_session_context`
+- `memorix_store_reasoning`
+- `memorix_search_reasoning`
+
+### Quality and Maintenance
+
+- `memorix_consolidate`
+- `memorix_deduplicate`
+- `memorix_formation_metrics`
+- `memorix_promote`
+- `memorix_skills`
+
+### Platform and Integrations
+
+- `memorix_rules_sync`
+- `memorix_workspace_sync`
+- `memorix_dashboard`
+
+### Team Tools
+
+- `team_manage`
+- `team_file_lock`
+- `team_task`
+- `team_message`
+
+The exact set may evolve, so AI systems should not hard-code stale tool counts.
+
+## Optional Enhancements
+
+### LLM Quality Mode
+
+If configured with an API key, Memorix can use LLMs for:
+
+- narrative compression
+- semantic deduplication
+- higher-quality ranking and enrichment
+
+### Local Vector Search
+
+Memorix works out of the box with BM25/full-text search. It can also use optional local vector providers for better semantic retrieval without requiring cloud embeddings.
+
+## Recommended AI Usage Pattern
+
+At session start:
+
+1. load session context with `memorix_session_start`
+2. in HTTP control-plane mode, pass `projectRoot` = the absolute current workspace or repo-root path when available
+3. if session start cannot resolve the project, retry with the correct path before using project-scoped tools
+4. search relevant recent memory
+5. fetch detail only when needed
+
+During work:
+
+1. store meaningful decisions, fixes, gotchas, and milestones
+2. resolve memories when tasks are completed
+3. prefer reasoning-rich summaries over raw logs
+
+At session end:
+
+1. store a concise session summary
+2. include what changed, why, current state, and next steps
+
+## When Memorix Is Strongest
+
+Memorix is strongest when the task is:
+
+- codebase-specific
+- project-memory heavy
+- multi-session
+- multi-agent
+- Git-aware
+- explanation-sensitive
+
+It is especially strong for:
+
+- "what changed recently?"
+- "why did we choose this?"
+- "what broke here before?"
+- "which commit relates to this behavior?"
+- "what should the next agent know before continuing?"
+
+## 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 Guide: https://github.com/AVIDS2/memorix/blob/main/docs/SETUP.md
+- Configuration Guide: https://github.com/AVIDS2/memorix/blob/main/docs/CONFIGURATION.md
+- Git Memory Guide: https://github.com/AVIDS2/memorix/blob/main/docs/GIT_MEMORY.md
+- Architecture: https://github.com/AVIDS2/memorix/blob/main/docs/ARCHITECTURE.md
+- API Reference: https://github.com/AVIDS2/memorix/blob/main/docs/API_REFERENCE.md
+- Changelog: https://github.com/AVIDS2/memorix/blob/main/CHANGELOG.md

package/llms.txt

@@ -0,0 +1,75 @@
+# Memorix
+
+> Open-source cross-agent memory layer for coding agents via MCP.
+
+Memorix is an open-source MCP server that gives coding agents persistent, project-aware memory across IDEs and sessions. It is compatible with Cursor, Claude Code, Codex, Windsurf, Gemini CLI, GitHub Copilot, Kiro, OpenCode, Antigravity, and Trae through MCP. It combines three layers in one system:
+
+- **Git Memory** for engineering truth from commits
+- **Reasoning Memory** for why decisions were made
+- **Cross-Agent Recall** so multiple IDEs and agents can share the same local memory base
+
+## What Memorix Is Best At
+
+- Turning `git commit` history into searchable memory with commit provenance and noise filtering
+- Preserving architecture decisions, bug fixes, gotchas, and reasoning across sessions
+- Sharing memory across Cursor, Windsurf, Claude Code, Codex, Copilot, Kiro, Antigravity, OpenCode, Trae, and Gemini CLI
+- Running a local memory control plane with search, detail, timeline, dashboard, retention, and team workflows
+
+## Quick Start
+
+```bash
+npm install -g memorix
+memorix init
+memorix serve
+```
+
+Memorix uses:
+
+- `memorix.yml` for behavior and project settings
+- `.env` for secrets such as API keys
+
+For the normal HTTP MCP + dashboard experience:
+
+```bash
+memorix background start
+```
+
+Use `memorix serve-http --port 3211` only when you want the same HTTP control plane in the foreground for debugging, manual supervision, or a custom port.
+
+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"
+    }
+  }
+}
+```
+
+In HTTP control-plane mode, agents should call `memorix_session_start` with `projectRoot` set to the **absolute path of the current workspace or repo root** when that path is available. Git remains the source of truth for the final project identity; `projectRoot` is the detection anchor that prevents cross-project drift.
+
+## Core Links
+
+- Primary AI operator guide: [docs/AGENT_OPERATOR_PLAYBOOK.md](https://github.com/AVIDS2/memorix/blob/main/docs/AGENT_OPERATOR_PLAYBOOK.md)
+- GitHub: [AVIDS2/memorix](https://github.com/AVIDS2/memorix)
+- npm: [memorix](https://www.npmjs.com/package/memorix)
+- Full AI-facing docs: [llms-full.txt](https://github.com/AVIDS2/memorix/blob/main/llms-full.txt)
+- Setup: [docs/SETUP.md](https://github.com/AVIDS2/memorix/blob/main/docs/SETUP.md)
+- Configuration: [docs/CONFIGURATION.md](https://github.com/AVIDS2/memorix/blob/main/docs/CONFIGURATION.md)
+- Git Memory: [docs/GIT_MEMORY.md](https://github.com/AVIDS2/memorix/blob/main/docs/GIT_MEMORY.md)

package/package.json

@@ -1,101 +1,110 @@
-{
-  "name": "memorix",
-  "version": "1.0.4",
-  "description": "Cross-Agent Memory Bridge — Persistent memory for AI coding agents across Cursor, Windsurf, Claude Code, Codex, Copilot, Kiro, Antigravity, Gemini CLI via MCP.",
-  "type": "module",
-  "sideEffects": false,
-  "bin": {
-    "memorix": "./dist/cli/index.js"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md",
-    "CLAUDE.md"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "start": "node dist/index.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run build && npm test"
-  },
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "model-context-protocol",
-    "cursor-mcp",
-    "windsurf-mcp",
-    "claude-code-memory",
-    "codex-mcp",
-    "copilot-mcp",
-    "kiro-mcp",
-    "antigravity-mcp",
-    "ai-coding-memory",
-    "cross-ide-sync",
-    "cross-agent-memory",
-    "context-persistence",
-    "agent-memory",
-    "knowledge-graph",
-    "workspace-sync",
-    "progressive-disclosure",
-    "session-memory",
-    "vector-search",
-    "rules-sync",
-    "project-skills"
-  ],
-  "author": "AVIDS2",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/AVIDS2/memorix.git"
-  },
-  "homepage": "https://github.com/AVIDS2/memorix#readme",
-  "bugs": {
-    "url": "https://github.com/AVIDS2/memorix/issues"
-  },
-  "funding": {
-    "type": "github",
-    "url": "https://github.com/sponsors/AVIDS2"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "dependencies": {
-    "@clack/prompts": "^0.9.1",
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "@orama/orama": "^3.1.0",
-    "@orama/plugin-data-persistence": "^3.1.0",
-    "citty": "^0.1.6",
-    "diff": "^7.0.0",
-    "dotenv": "^17.3.1",
-    "gpt-tokenizer": "^2.8.0",
-    "gray-matter": "^4.0.3",
-    "js-yaml": "^3.13.1",
-    "remark": "^15.0.1",
-    "remark-stringify": "^11.0.0",
-    "zod": "^3.24.0"
-  },
-  "optionalDependencies": {
-    "@huggingface/transformers": "^3.0.0",
-    "fastembed": "^1.14.4"
-  },
-  "devDependencies": {
-    "@types/diff": "^7.0.0",
-    "@types/node": "^22.0.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
-  }
-}
+{
+  "name": "memorix",
+  "version": "1.0.6",
+  "description": "Open-source cross-agent memory layer for coding agents across Cursor, Claude Code, Codex, Windsurf, Gemini CLI, Copilot, Kiro, OpenCode, Antigravity, and Trae via MCP.",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "memorix": "./dist/cli/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CLAUDE.md",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "cursor-mcp",
+    "windsurf-mcp",
+    "claude-code-memory",
+    "codex-mcp",
+    "copilot-mcp",
+    "kiro-mcp",
+    "antigravity-mcp",
+    "ai-coding-memory",
+    "cross-ide-sync",
+    "cross-agent-memory",
+    "context-persistence",
+    "agent-memory",
+    "knowledge-graph",
+    "workspace-sync",
+    "progressive-disclosure",
+    "session-memory",
+    "vector-search",
+    "rules-sync",
+    "project-skills"
+  ],
+  "author": "AVIDS2",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AVIDS2/memorix.git"
+  },
+  "homepage": "https://github.com/AVIDS2/memorix#readme",
+  "bugs": {
+    "url": "https://github.com/AVIDS2/memorix/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/AVIDS2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@orama/orama": "^3.1.0",
+    "@orama/plugin-data-persistence": "^3.1.0",
+    "citty": "^0.1.6",
+    "cytoscape": "^3.33.1",
+    "cytoscape-dagre": "^2.5.0",
+    "dagre": "^0.8.5",
+    "diff": "^7.0.0",
+    "dotenv": "^17.3.1",
+    "gpt-tokenizer": "^2.8.0",
+    "gray-matter": "^4.0.3",
+    "ink": "^6.8.0",
+    "js-yaml": "^3.13.1",
+    "react": "^19.2.4",
+    "remark": "^15.0.1",
+    "remark-stringify": "^11.0.0",
+    "zod": "^3.24.0"
+  },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^3.0.0",
+    "fastembed": "^1.14.4"
+  },
+  "devDependencies": {
+    "@types/diff": "^7.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.14",
+    "ink-testing-library": "^4.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}