memorix 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.4] — 2026-03-17
+
+### Added
+- **Git Memory pipeline** — `git commit` can now flow directly into Memorix via `memorix git-hook`, `memorix git-hook-uninstall`, and `memorix ingest commit --auto`. Stored observations now carry `source` and `commitHash`, and Git memories can be filtered explicitly with `source: "git"`.
+- **Reasoning Memory tools** — Added `memorix_store_reasoning` and `memorix_search_reasoning` so design rationale, alternatives, constraints, and risks can be stored and searched as a first-class memory layer.
+- **Source-aware retrieval and cross-linking** — Search now boosts Git, reasoning, and problem-solution memories differently based on query intent. Git memories and reasoning memories can cross-reference each other via related commits and shared entities.
+- **Structured config model** — Added project/user `memorix.yml`, project/user `.env` loading, `memorix init`, and configuration provenance diagnostics in `memorix status`.
+- **Dashboard control plane upgrades** — Added Git Memory, Config Provenance, and Identity Health views, plus richer stats and a stabilized graph layout for the HTTP dashboard.
+
+### Changed
+- **Documentation consolidation** — Reworked README, README.zh-CN, setup, architecture, API reference, configuration, Git Memory, and development guides so they match the current product model: local-first platform, `memorix.yml + .env`, Git Memory, HTTP dashboard, and the four-layer architecture.
+- **Project detection model** — Project identity now centers on real Git roots, MCP roots support, system-directory fallback handling, and runtime project switching instead of older placeholder-style fallback identities.
+- **Dashboard usage model** — `memorix serve-http --port 3211` is now the primary “control plane” entrypoint when you want HTTP transport, collaboration features, and dashboard access in one place.
+
+### Fixed
+- **Project identity drift** — Fixed Codex/Windsurf startup issues that produced `local/System32`, IDE-installation-directory identities, or other incorrect local project bindings.
+- **Worktree-safe Git hooks** — Hook installation, uninstall, auto-install checks, and status reporting now resolve hooks directories correctly for both normal repos and Git worktrees.
+- **Runtime config correctness** — Fixed project-level `memorix.yml` not reaching runtime getters, `.env` values leaking across project switches, and legacy `config.json` not showing up correctly in provenance diagnostics.
+- **Git Memory quality** — Added noise filtering, preserved release/version milestone commits, and implemented `memorix ingest commit --force` as an escape hatch for manual ingestion.
+- **Cross-project detail retrieval** — Global search results can now be opened reliably with project-aware refs instead of colliding on observation IDs from different projects.
+- **Skill generation noise** — `memorix_skills generate` now filters low-signal command-history observations like `git`, `gh`, `npm`, and `npx` so generated skills stay project-relevant.
+- **OpenCode static plugin noise** — Merged the first external PR to silence `console.log` spam in the static OpenCode plugin without reintroducing session lifecycle side effects.
+- **CI/publish flow** — Restored CI green after type/test regressions and changed npm publishing workflow to manual trigger instead of automatic release publishing.
+
+### Stats
+- **Tests:** 879/879 passing across 68 files
+- **Runtime modes:** stdio MCP (`memorix serve`), HTTP MCP + dashboard (`memorix serve-http --port 3211`), and standalone dashboard remain supported
+
+---
+
+## [1.0.3] — 2026-03-14
+
+### Added
+- **Memory Formation Pipeline** — Three-stage pipeline (Extract → Resolve → Evaluate) runs in shadow mode on every `memorix_store` call and hooks trigger. Collects quality metrics without affecting storage decisions.
+  - **Extract**: Automatic fact extraction from narratives, title normalization, entity resolution against Knowledge Graph, observation type verification.
+  - **Resolve**: 4 resolution actions (new/merge/evolve/discard) based on similarity scoring, word overlap, and contradiction detection.
+  - **Evaluate**: Multi-factor knowledge value assessment (type weight, fact density, specificity, causal reasoning, noise detection). Categorizes memories as core/contextual/ephemeral.
+- **`memorix_formation_metrics` tool** — New MCP tool to query aggregated Formation Pipeline metrics (value scores, resolution actions, extraction rates, processing times).
+- **`getEntityNames()` method** on `KnowledgeGraphManager` for Formation Pipeline entity resolution.
+
+### Stats
+- **Default MCP Tools:** 23 (+1: `memorix_formation_metrics`)
+- **Tests:** 803/803 passing across 60 files (+50 new Formation Pipeline tests)
+- **Hooks safety:** handler.ts +21 lines (shadow call only), zero modification to existing hook logic
+
+---
+
 ## [1.0.2] — 2026-03-14
 
 ### Fixed

package/README.md

@@ -5,339 +5,216 @@
 <h1 align="center">Memorix</h1>
 
 <p align="center">
-  <strong>Persistent memory layer for AI coding agents.</strong><br>
-  One MCP server. Ten agents. Zero context loss.
+  <strong>Local-first memory platform for AI coding agents.</strong><br>
+  Git truth, reasoning memory, and cross-agent recall in one MCP server.
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/memorix"><img src="https://img.shields.io/npm/v/memorix.svg?style=flat-square&color=cb3837" alt="npm"></a>
   <a href="https://www.npmjs.com/package/memorix"><img src="https://img.shields.io/npm/dm/memorix.svg?style=flat-square&color=blue" alt="downloads"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green.svg?style=flat-square" alt="license"></a>
-  <a href="https://github.com/AVIDS2/memorix"><img src="https://img.shields.io/github/stars/AVIDS2/memorix?style=flat-square&color=yellow" alt="stars"></a>
-  <img src="https://img.shields.io/badge/tests-753%20passed-brightgreen?style=flat-square" alt="tests">
   <a href="https://github.com/AVIDS2/memorix/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/AVIDS2/memorix/ci.yml?style=flat-square&label=CI" alt="CI"></a>
+  <a href="https://github.com/AVIDS2/memorix"><img src="https://img.shields.io/github/stars/AVIDS2/memorix?style=flat-square&color=yellow" alt="stars"></a>
 </p>
 
 <p align="center">
-  <strong>v1.0 Stable | 22 MCP tools | Auto-cleanup | Multi-agent collaboration | 10 IDEs supported</strong>
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/-Cursor-orange?style=flat-square" alt="Cursor">
-  <img src="https://img.shields.io/badge/-Windsurf-blue?style=flat-square" alt="Windsurf">
-  <img src="https://img.shields.io/badge/-Claude%20Code-purple?style=flat-square" alt="Claude Code">
-  <img src="https://img.shields.io/badge/-Codex-green?style=flat-square" alt="Codex">
-  <img src="https://img.shields.io/badge/-Copilot-lightblue?style=flat-square" alt="Copilot">
-  <img src="https://img.shields.io/badge/-Kiro-red?style=flat-square" alt="Kiro">
-  <img src="https://img.shields.io/badge/-Antigravity-grey?style=flat-square" alt="Antigravity">
-  <img src="https://img.shields.io/badge/-OpenCode-teal?style=flat-square" alt="OpenCode">
-  <img src="https://img.shields.io/badge/-Trae-FF6B35?style=flat-square" alt="Trae">
-  <img src="https://img.shields.io/badge/-Gemini%20CLI-4285F4?style=flat-square" alt="Gemini CLI">
+  <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="#features">Features</a> ·
-  <a href="#architecture">Architecture</a> ·
+  <a href="#how-it-works">How It Works</a> ·
+  <a href="#documentation">Documentation</a> ·
   <a href="docs/SETUP.md">Setup Guide</a>
 </p>
 
 ---
 
-## Introduction
+## Why Memorix
 
-AI coding agents lose all context between sessions. Switch IDEs and previous decisions, debugging history, and architectural knowledge are gone. Memorix provides a shared, persistent memory layer across agents and sessions — storing decisions, gotchas, and project knowledge that any agent can retrieve instantly.
+Most AI coding agents remember only the current thread. Memorix gives them a shared, persistent memory layer across IDEs, sessions, and projects.
 
-```
-Session 1 (Cursor):      "Use JWT with refresh tokens, 15-min expiry"  → stored as decision
-Session 2 (Claude Code): "Add login endpoint"  → retrieves the decision → implements correctly
-```
+What makes Memorix different:
 
-No re-explaining. No copy-pasting. No vendor lock-in.
-
-### Core Capabilities
-
-- **Cross-Agent Memory**: All agents share the same memory store. Store in Cursor, retrieve in Claude Code.
-- **Multi-Agent Collaboration**: Team tools for agent coordination — join/leave, file locks, task boards, and cross-IDE messaging via shared `team-state.json`.
-- **Auto-Cleanup on Startup**: Background retention archiving and intelligent deduplication (LLM or heuristic) run automatically — zero manual maintenance.
-- **Dual-Mode Quality**: Free heuristic engine for basic dedup; optional LLM mode for intelligent compression, reranking, and conflict resolution.
-- **3-Layer Progressive Disclosure**: Search returns compact indices (~50 tokens/result), timeline shows chronological context, detail provides full content. ~10x token savings over full-text retrieval.
-- **Mini-Skills**: Promote high-value observations to permanent skills that auto-inject at every session start. Critical knowledge never decays.
-- **Auto-Memory Hooks**: Automatically capture decisions, errors, and gotchas from IDE tool calls. Pattern detection in English and Chinese.
-- **Knowledge Graph**: Entity-relation model compatible with [MCP Official Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory). Auto-creates relations from entity extraction.
+- **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.
+- **Memory Quality Pipeline**: formation, compaction, retention, and source-aware retrieval work together instead of acting like isolated tools.
 
 ---
 
 ## Quick Start
 
+Install globally:
+
 ```bash
 npm install -g memorix
 ```
 
-Add to your agent's MCP config:
-
-<details open>
-<summary><strong>Cursor</strong> · <code>.cursor/mcp.json</code></summary>
-
-```json
-{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
-```
-</details>
-
-<details>
-<summary><strong>Claude Code</strong></summary>
+Initialize project config:
 
 ```bash
-claude mcp add memorix -- memorix serve
+memorix init
 ```
-</details>
 
-<details>
-<summary><strong>Windsurf</strong> · <code>~/.codeium/windsurf/mcp_config.json</code></summary>
+Memorix uses two files with two roles:
 
-```json
-{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
-```
-</details>
-
-<details>
-<summary><strong>VS Code Copilot</strong> · <code>.vscode/mcp.json</code></summary>
-
-```json
-{ "servers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
-```
-</details>
+- `memorix.yml` for behavior and project settings
+- `.env` for secrets such as API keys
 
-<details>
-<summary><strong>Codex</strong> · <code>~/.codex/config.toml</code></summary>
+Choose one runtime mode:
 
-```toml
-[mcp_servers.memorix]
-command = "memorix"
-args = ["serve"]
+```bash
+memorix serve
 ```
-</details>
 
-<details>
-<summary><strong>Kiro</strong> · <code>.kiro/settings/mcp.json</code></summary>
+Use `serve` for normal stdio MCP integrations.
 
-```json
-{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
+```bash
+memorix serve-http --port 3211
 ```
-</details>
 
-<details>
-<summary><strong>Antigravity</strong> · <code>~/.gemini/antigravity/mcp_config.json</code></summary>
+Use `serve-http` when you want the HTTP transport, collaboration features, and the dashboard on the same port.
 
-```json
-{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"], "env": { "MEMORIX_PROJECT_ROOT": "/your/project/path" } } } }
-```
-</details>
+Add Memorix to your MCP client:
 
-<details>
-<summary><strong>OpenCode</strong> · <code>~/.config/opencode/config.json</code></summary>
+<details open>
+<summary><strong>Cursor</strong> · <code>.cursor/mcp.json</code></summary>
 
 ```json
-{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "memorix",
+      "args": ["serve"]
+    }
+  }
+}
 ```
 </details>
 
 <details>
-<summary><strong>Trae</strong> · <code>~/%APPDATA%/Trae/User/mcp.json</code></summary>
+<summary><strong>Claude Code</strong></summary>
 
-```json
-{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
+```bash
+claude mcp add memorix -- memorix serve
 ```
 </details>
 
 <details>
-<summary><strong>Gemini CLI</strong> · <code>.gemini/settings.json</code></summary>
+<summary><strong>Codex</strong> · <code>~/.codex/config.toml</code></summary>
 
-```json
-{ "mcpServers": { "memorix": { "command": "memorix", "args": ["serve"] } } }
+```toml
+[mcp_servers.memorix]
+command = "memorix"
+args = ["serve"]
 ```
 </details>
 
-Restart your agent. No API keys required. No cloud. No external dependencies.
-
-> **Auto-update**: Memorix checks for updates on startup (once per 24h) and self-updates in the background.
-
-> **Note**: Do not use `npx` — it re-downloads on each invocation and causes MCP timeout. Use global install.
->
-> [Full setup guide](docs/SETUP.md) · [Troubleshooting](docs/SETUP.md#troubleshooting)
+For the full IDE matrix, Windows notes, and troubleshooting, see [docs/SETUP.md](docs/SETUP.md).
 
 ---
 
-## Features
-
-### 22 MCP Tools (Default)
-
-| Category | Tools |
-|----------|-------|
-| **Memory** | `memorix_store` · `memorix_search` · `memorix_detail` · `memorix_timeline` · `memorix_resolve` · `memorix_deduplicate` · `memorix_suggest_topic_key` |
-| **Sessions** | `memorix_session_start` · `memorix_session_end` · `memorix_session_context` |
-| **Skills** | `memorix_skills` · `memorix_promote` |
-| **Workspace** | `memorix_workspace_sync` · `memorix_rules_sync` |
-| **Maintenance** | `memorix_retention` · `memorix_consolidate` · `memorix_transfer` |
-| **Team** | `team_manage` · `team_file_lock` · `team_task` · `team_message` |
-| **Dashboard** | `memorix_dashboard` |
-
-<details>
-<summary><strong>+9 Optional: Knowledge Graph tools</strong> (enable in <code>~/.memorix/settings.json</code>)</summary>
-
-`create_entities` · `create_relations` · `add_observations` · `delete_entities` · `delete_observations` · `delete_relations` · `search_nodes` · `open_nodes` · `read_graph`
-
-Enable with: `{ "knowledgeGraph": true }` in `~/.memorix/settings.json`
-</details>
-
-### Observation Types
+## Core Workflows
 
-Nine structured types for classifying stored knowledge:
+### 1. Store and retrieve memory
 
-`session-request` · `gotcha` · `problem-solution` · `how-it-works` · `what-changed` · `discovery` · `why-it-exists` · `decision` · `trade-off`
+Use MCP tools such as:
 
-### Hybrid Search
+- `memorix_store`
+- `memorix_search`
+- `memorix_detail`
+- `memorix_timeline`
+- `memorix_resolve`
 
-BM25 fulltext search works out of the box with minimal resources (~50MB RAM). Semantic vector search is opt-in with three provider options:
+This covers decisions, gotchas, problem-solution notes, and session handoff context.
 
-| Provider | Configuration | Resources | Quality |
-|----------|--------------|-----------|---------|
-| **API** (recommended) | `MEMORIX_EMBEDDING=api` | Zero local RAM | Highest |
-| **fastembed** | `MEMORIX_EMBEDDING=fastembed` | ~300MB RAM | High |
-| **transformers** | `MEMORIX_EMBEDDING=transformers` | ~500MB RAM | High |
-| **Off** (default) | `MEMORIX_EMBEDDING=off` | ~50MB RAM | BM25 only |
+### 2. Capture Git truth automatically
 
-API embedding works with any OpenAI-compatible endpoint — OpenAI, Qwen/DashScope, OpenRouter, Ollama, or any proxy:
+Install the post-commit hook:
 
 ```bash
-MEMORIX_EMBEDDING=api
-MEMORIX_EMBEDDING_API_KEY=sk-xxx
-MEMORIX_EMBEDDING_MODEL=text-embedding-3-small
-MEMORIX_EMBEDDING_BASE_URL=https://api.openai.com/v1    # optional
-MEMORIX_EMBEDDING_DIMENSIONS=512                         # optional
+memorix git-hook --force
 ```
 
-Embedding infrastructure includes 10K LRU cache with disk persistence, batch API calls (up to 2048 texts per request), parallel processing (4 concurrent chunks), and text normalization for improved cache hit rates. Zero external dependencies — no Chroma, no SQLite.
-
-For local embedding:
+Or ingest manually:
 
 ```bash
-npm install -g fastembed                     # ONNX runtime
-npm install -g @huggingface/transformers     # JS/WASM runtime
+memorix ingest commit
+memorix ingest log --count 20
 ```
 
-### LLM Enhanced Mode
-
-Optional LLM integration that significantly improves memory quality. Three capabilities layered on top of the base search:
+Git memories are stored with `source='git'`, commit hashes, changed files, and noise filtering.
 
-| Capability | Description | Measured Impact |
-|-----------|-------------|-----------------|
-| **Narrative Compression** | Compresses verbose observations before storage, preserving all technical facts | 27% token reduction (up to 44% on narrative-heavy content) |
-| **Search Reranking** | LLM reranks search results by semantic relevance to the current query | 60% of queries improved, 0% degraded |
-| **Compact on Write** | Detects duplicates and conflicts at write time; merges, updates, or skips as appropriate | Prevents redundant storage, resolves contradictions |
-
-Smart filtering ensures LLM calls are only made when beneficial — structured content like commands and file paths is bypassed automatically.
+### 3. Run the control plane
 
 ```bash
-MEMORIX_LLM_API_KEY=sk-xxx
-MEMORIX_LLM_PROVIDER=openai          # openai | anthropic | openrouter | custom
-MEMORIX_LLM_MODEL=gpt-4.1-nano       # any chat completion model
-MEMORIX_LLM_BASE_URL=https://...     # custom endpoint (optional)
+memorix serve-http --port 3211
 ```
 
-Memorix auto-detects existing environment variables:
-
-| Variable | Provider |
-|----------|----------|
-| `OPENAI_API_KEY` | OpenAI |
-| `ANTHROPIC_API_KEY` | Anthropic |
-| `OPENROUTER_API_KEY` | OpenRouter |
-
-**Without LLM**: Free heuristic deduplication (similarity-based rules). **With LLM**: Intelligent compression, contextual reranking, contradiction detection, and fact extraction.
+Then open:
 
-### Mini-Skills
+- MCP HTTP endpoint: `http://localhost:3211/mcp`
+- Dashboard: `http://localhost:3211`
 
-Promote high-value observations to permanent skills using `memorix_promote`. Mini-skills are:
+This mode gives you collaboration tools, project identity diagnostics, config provenance, Git Memory views, and the dashboard in one place.
 
-- **Permanent** — exempt from retention decay, never archived
-- **Auto-injected** — loaded into context at every `memorix_session_start`
-- **Project-scoped** — isolated per project, no cross-project pollution
-
-Use this for critical knowledge that must survive indefinitely: deployment procedures, architectural constraints, recurring gotchas.
-
-### Team Collaboration
+---
 
-Multiple agents working in the same workspace can coordinate via 4 team tools:
+## How It Works
 
-| Tool | Actions | Purpose |
-|------|---------|---------|
-| `team_manage` | join, leave, status | Agent registry — see who's active |
-| `team_file_lock` | lock, unlock, status | Advisory file locks to prevent conflicts |
-| `team_task` | create, claim, complete, list | Shared task board with dependencies |
-| `team_message` | send, broadcast, inbox | Direct and broadcast messaging |
+```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"]
+```
 
-State is persisted to `team-state.json` and shared across all IDE processes. See [TEAM.md](TEAM.md) for the full protocol.
+### Memory Layers
 
-### Auto-Memory Hooks
+- **Observation Memory**: what changed, how something works, gotchas, problem-solution notes
+- **Reasoning Memory**: why a choice was made, alternatives, trade-offs, risks
+- **Git Memory**: immutable engineering facts derived from commits
 
-```bash
-memorix hooks install
-```
+### Retrieval Model
 
-Captures decisions, errors, and gotchas automatically from IDE tool calls. Pattern detection supports English and Chinese. Smart filtering applies 30-second cooldown and skips trivial commands. High-value memories are injected at session start.
+- 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
 
-### Interactive CLI
+---
 
-```bash
-memorix              # Interactive menu
-memorix configure    # LLM + Embedding provider setup
-memorix status       # Project info and statistics
-memorix dashboard    # Web UI at localhost:3210
-memorix hooks install # Install auto-capture for IDEs
-```
+## Documentation
 
----
+### Getting Started
 
-## Architecture
+- [Setup Guide](docs/SETUP.md)
+- [Configuration Guide](docs/CONFIGURATION.md)
 
-```mermaid
-graph TB
-    A["Cursor · Claude Code · Windsurf · Codex · +6 more"]
-    A -->|MCP stdio| Core
-    Core["Memorix MCP Server\n22 Default Tools · Auto-Hooks · Auto-Cleanup"]
-    Core --> Search["Search Pipeline\nBM25 + Vector + Rerank"]
-    Core --> Team["Team Collab\nAgents · Tasks · Locks · Msgs"]
-    Core --> Sync["Rules & Workspace Sync\n10 Adapters"]
-    Core --> Cleanup["Auto-Cleanup\nRetention + LLM Dedup"]
-    Core --> KG["Knowledge Graph\nEntities · Relations"]
-    Search --> Disk["~/.memorix/data/\nobservations · sessions · mini-skills · team-state · entities · relations"]
-    Team --> Disk
-    KG --> Disk
-```
+### Product and Architecture
 
-### Search Pipeline
+- [Architecture](docs/ARCHITECTURE.md)
+- [Memory Formation Pipeline](docs/MEMORY_FORMATION_PIPELINE.md)
+- [Design Decisions](docs/DESIGN_DECISIONS.md)
 
-Three-stage retrieval with progressive quality enhancement:
+### Reference
 
-```
-Stage 1:  Orama (BM25 + Vector Hybrid)  →  Top-N candidates
-Stage 2:  LLM Reranking (optional)      →  Reordered by semantic relevance
-Stage 3:  Recency + Project Affinity    →  Final scored results
-```
+- [API Reference](docs/API_REFERENCE.md)
+- [Git Memory Guide](docs/GIT_MEMORY.md)
+- [Modules](docs/MODULES.md)
 
-### Write Pipeline
+### Development
 
-```
-Input  →  LLM Compression (optional)  →  Compact on Write (dedup/merge)  →  Store + Index
-```
+- [Development Guide](docs/DEVELOPMENT.md)
+- [Known Issues and Roadmap](docs/KNOWN_ISSUES_AND_ROADMAP.md)
 
-### Key Design Decisions
+### AI-Facing Project Docs
 
-- **Project isolation**: Auto-detected from `git remote`. Scoped search by default.
-- **Shared storage**: All agents read/write `~/.memorix/data/`. Cross-IDE by design.
-- **Token efficiency**: 3-layer progressive disclosure (search, timeline, detail). ~10x savings.
-- **Graceful degradation**: Every LLM and embedding feature is optional. Core functionality requires zero configuration.
+- [`llms.txt`](llms.txt)
+- [`llms-full.txt`](llms-full.txt)
 
 ---
 
@@ -345,22 +222,28 @@ Input  →  LLM Compression (optional)  →  Compact on Write (dedup/merge)  →
 
 ```bash
 git clone https://github.com/AVIDS2/memorix.git
-cd memorix && npm install
+cd memorix
+npm install
 
-npm run dev       # watch mode
-npm test          # 753 tests
-npm run build     # production build
+npm run dev
+npm test
+npm run build
 ```
 
-[Architecture](docs/ARCHITECTURE.md) · [API Reference](docs/API_REFERENCE.md) · [Modules](docs/MODULES.md) · [Design Decisions](docs/DESIGN_DECISIONS.md)
+Key local commands:
 
-> For AI agents: [`llms.txt`](llms.txt) · [`llms-full.txt`](llms-full.txt)
+```bash
+memorix status
+memorix dashboard
+memorix serve-http --port 3211
+memorix git-hook --force
+```
 
 ---
 
 ## Acknowledgements
 
-Built on ideas from [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service), [MemCP](https://github.com/maydali28/memcp), [claude-mem](https://github.com/anthropics/claude-code), and [Mem0](https://github.com/mem0ai/mem0).
+Memorix builds on ideas from [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service), [MemCP](https://github.com/maydali28/memcp), [claude-mem](https://github.com/anthropics/claude-code), [Mem0](https://github.com/mem0ai/mem0), and the broader MCP ecosystem.
 
 ## Star History