memorix 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/CHANGELOG.md +20 -1
  2. package/README.md +278 -173
  3. package/dist/cli/index.js +106 -11
  4. package/dist/cli/index.js.map +1 -1
  5. package/dist/index.js +96 -9
  6. package/dist/index.js.map +1 -1
  7. package/package.json +19 -6
  8. package/examples/CLAUDE.md +0 -27
  9. package/examples/claude-desktop-config.json +0 -8
  10. package/examples/cursor-mcp.json +0 -8
  11. package/examples/windsurf-mcp.json +0 -8
package/CHANGELOG.md CHANGED
@@ -1,6 +1,25 @@
1
1
  # Changelog
2
2
 
3
- ## 0.1.0 (2026-02-14)
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ ## [0.5.0] — 2026-02-15
6
+
7
+ ### Added
8
+ - **Antigravity Adapter**: Full support for Antigravity/Gemini IDE (MCP config + rules)
9
+ - **Copilot Adapter**: VS Code Copilot MCP config adapter + rules format adapter
10
+ - **Comprehensive Documentation**: 7 developer docs in `docs/` (Architecture, Modules, API Reference, Design Decisions, Development Guide, Known Issues & Roadmap, AI Context)
11
+ - **8 new npm keywords**: antigravity, mcp-tool, memory-layer, ai-memory, progressive-disclosure, orama, vector-search, bm25
12
+ - `prepublishOnly` now runs `npm test` in addition to build
13
+
14
+ ### Changed
15
+ - README completely rewritten with clearer structure, npx zero-install setup, 6 agent configs, comparison table, Progressive Disclosure example, and architecture diagram
16
+ - `description` field expanded for better npm search ranking
17
+ - `files` array cleaned up (removed unused `examples` directory)
18
+
19
+ ### Fixed
20
+ - 274 tests passing (up from 219), zero regressions
21
+
22
+ ## [0.1.0] — 2026-02-14
4
23
 
5
24
  ### Core
6
25
  - Knowledge Graph: Entity-Relation-Observation model (MCP Official compatible)
package/README.md CHANGED
@@ -1,171 +1,212 @@
1
- # Memorix — Cross-Agent Memory Bridge
1
+ <p align="center">
2
+ <h1 align="center">🧠 Memorix</h1>
3
+ <p align="center"><strong>Cross-Agent Memory Bridge — Universal memory layer for AI coding agents via MCP</strong></p>
4
+ <p align="center">
5
+ <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 version"></a>
6
+ <a href="https://www.npmjs.com/package/memorix"><img src="https://img.shields.io/npm/dm/memorix.svg?style=flat-square&color=blue" alt="npm downloads"></a>
7
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green.svg?style=flat-square" alt="License"></a>
8
+ <a href="https://github.com/AVIDS2/memorix"><img src="https://img.shields.io/github/stars/AVIDS2/memorix?style=flat-square&color=yellow" alt="GitHub stars"></a>
9
+ <img src="https://img.shields.io/badge/tests-274%20passed-brightgreen?style=flat-square" alt="Tests">
10
+ </p>
11
+ <p align="center">
12
+ <a href="#-quick-start">Quick Start</a> •
13
+ <a href="#-features">Features</a> •
14
+ <a href="#-agent-configuration">Agent Config</a> •
15
+ <a href="#-how-it-works">How It Works</a> •
16
+ <a href="#-development">Development</a>
17
+ </p>
18
+ </p>
19
+
20
+ ---
21
+
22
+ > **Your AI forgot what you discussed yesterday? Not anymore.**
23
+ >
24
+ > Memorix stores and indexes project knowledge — architecture decisions, bug fixes, gotchas, code patterns — and exposes it via [MCP](https://modelcontextprotocol.io/) so **any AI coding agent** can access it. It also **syncs MCP configs, rules, skills, and workflows** across all your agents automatically.
25
+
26
+ ---
27
+
28
+ ## ⚡ Quick Start
29
+
30
+ ### 30-Second Setup (Zero Install)
31
+
32
+ Add Memorix to your agent's MCP config — **that's it**. No global install needed.
33
+
34
+ **Windsurf** → `~/.codeium/windsurf/mcp_config.json`
35
+ ```json
36
+ {
37
+ "mcpServers": {
38
+ "memorix": {
39
+ "command": "npx",
40
+ "args": ["-y", "memorix@latest", "serve"]
41
+ }
42
+ }
43
+ }
44
+ ```
2
45
 
3
- > Universal memory layer for AI coding agents via MCP
46
+ Restart your agent and Memorix is running! 🎉
4
47
 
5
- [![npm version](https://img.shields.io/npm/v/memorix.svg)](https://www.npmjs.com/package/memorix)
6
- [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
48
+ > 💡 More agent configs: [Cursor](#cursor) • [Claude Code](#claude-code) • [Codex](#codex) • [VS Code Copilot](#vs-code-copilot) • [Antigravity](#antigravity)
7
49
 
8
- ## What is Memorix?
50
+ ### Or Install Globally
9
51
 
10
- Memorix is a lightweight local MCP server that acts as a **universal memory layer** across AI coding agents. Your knowledge from **Windsurf, Cursor, Claude Code, Codex, and VS Code Copilot** is stored once and shared everywhere.
52
+ ```bash
53
+ npm install -g memorix
54
+ ```
11
55
 
12
- ### The Problem
56
+ Then use `"command": "memorix"` instead of `"command": "npx"` in your config.
13
57
 
14
- - claude-mem only serves Claude Code
15
- - mcp-memory-service has no cross-agent workspace sync
16
- - Your architecture decisions in Cursor are invisible to Claude Code
17
- - Bug fix knowledge in Windsurf doesn't transfer to Codex
18
- - **No one bridges memory AND workspace configs across agents**
58
+ ---
19
59
 
20
- ### The Solution
60
+ ## 🤔 The Problem
21
61
 
22
- Memorix stores and indexes project knowledge (architecture decisions, bug fixes, code style preferences) and exposes it via MCP — so **any MCP-supporting agent** can access it. It also **syncs MCP configs, rules, skills, and workflows** across all your agents automatically.
62
+ | Situation | Pain |
63
+ |-----------|------|
64
+ | Architecture decisions in Cursor | Invisible to Claude Code |
65
+ | Bug fix knowledge in Windsurf | Doesn't transfer to Codex |
66
+ | MCP server configs | Manually copy-paste between agents |
67
+ | Agent rules & skills | Stuck in one IDE |
68
+ | Start a new session | Re-explain everything from scratch |
23
69
 
24
- ## Features
70
+ **No one bridges memory AND workspace configs across agents — until now.**
25
71
 
26
- ### P0 — Core (Current)
72
+ ---
27
73
 
28
- - **Knowledge Graph**: Entity-Relation model (MCP Official Memory Server compatible)
29
- - **3-Layer Progressive Disclosure**: Token-efficient search (claude-mem pattern)
30
- - L1: Compact index (~50-100 tokens/result)
31
- - L2: Timeline context
32
- - L3: Full details on demand (~500-1000 tokens/result)
33
- - **9 Observation Types**: 🎯🔴🟡🔵🟢🟣🟠🟤⚖️
34
- - **Full-text Search**: Powered by Orama
35
- - **Per-project Isolation**: Auto-detected via Git remote
36
- - **MCP Compatible**: All 9 official Memory Server tools + 5 Memorix extensions
74
+ ## ✨ Features
37
75
 
38
- ### P1 — Smart Search
76
+ ### 🧠 Smart Memory
39
77
 
40
- - **Hybrid Search**: Full-text (BM25) + Vector (semantic) via Orama
41
- - **Vector Embeddings**: Optional `fastembed` (local ONNX, zero API calls)
42
- - **Graceful Degradation**: No fastembed? Falls back to BM25 fulltext automatically
43
- - **Token Budget**: `maxTokens` parameter trims results to fit context windows
78
+ - **Knowledge Graph** — Entity-Relation model, [MCP Official Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) compatible
79
+ - **9 Observation Types** — 🎯 session-request 🔴 gotcha 🟡 problem-solution 🔵 how-it-works 🟢 what-changed 🟣 discovery 🟠 why-it-exists 🟤 decision ⚖️ trade-off
80
+ - **Auto-Enrichment** — Automatically extracts file paths, module names, CamelCase identifiers from your narratives
81
+ - **Auto-Relations** — Detects causal language ("because", "due to", "fixed by") and auto-creates typed graph relations
82
+ - **Memory Decay** — Exponential decay scoring with immunity rules, so old memories fade while critical ones persist forever
44
83
 
45
- ### P2 — Cross-Agent Workspace Sync
84
+ ### 🔍 Token-Efficient Search
46
85
 
47
- - **5 Agent Adapters**: Windsurf, Cursor, Claude Code, Codex, VS Code Copilot
48
- - **MCP Config Sync**: Detect and migrate MCP server configs across agents (merges into existing files — never overwrites)
49
- - **Rules Parser**: 4 format adapters (Cursor `.mdc`, Claude Code `CLAUDE.md`, Codex `SKILL.md`, Windsurf `.windsurfrules`)
50
- - **Rules Syncer**: Scan → Deduplicate → Conflict detection → Cross-format generation
51
- - **Skills Sync**: Scan `.codex/skills/`, `.cursor/skills/`, `.windsurf/skills/`, `.claude/skills/` → copy entire skill folders across agents
52
- - **Sync Advisory**: On first `memorix_search`, auto-detects available configs/skills from other agents and prompts the user
53
- - **Selective Sync**: Sync specific items by name (e.g. `items=["figma-remote-mcp-server", "create-subagent"]`)
54
- - **Apply with Safety**: Backup → Atomic write → Auto-rollback on failure
86
+ - **3-Layer Progressive Disclosure** — Based on [claude-mem](https://github.com/anthropics/claude-code) (~10x token savings)
87
+ - **L1** `memorix_search` → Compact index (~50-100 tokens/result)
88
+ - **L2** `memorix_timeline` → Chronological context
89
+ - **L3** `memorix_detail` → Full details on demand (~500-1000 tokens/result)
90
+ - **Hybrid Search** — Full-text (BM25) + Vector (semantic) via [Orama](https://github.com/orama/orama)
91
+ - **Token Budget** — `maxTokens` parameter auto-trims results to fit context windows
55
92
 
56
- ### P3 — Auto-Memory Hooks
93
+ ### 🔄 Cross-Agent Workspace Sync
57
94
 
58
- - **Hook Events**: `user_prompt`, `post_response`, `post_edit`, `post_command`, `post_tool`, `session_end`
59
- - **Agent Normalizer**: Maps Windsurf/Cursor/Claude Code/Codex native events to unified hook events
60
- - **Pattern Detection**: Auto-detects decisions, errors, gotchas, configurations, learnings, implementations
61
- - **Cooldown Filtering**: Prevents duplicate storage within configurable time windows
62
- - **Noise Filtering**: Skips trivial commands (`ls`, `cat`, `pwd`, etc.)
63
- - **Agent Rules**: Auto-installs `.windsurf/rules/memorix.md` (or equivalent) to guide agents in proactive memory management
64
- - **One-Command Install**: `memorix hooks install` sets up hooks + rules for your agent
95
+ - **6 Agent Adapters** — Windsurf, Cursor, Claude Code, Codex, VS Code Copilot, Antigravity
96
+ - **MCP Config Migration** — Detect and migrate MCP server configs (merges — never overwrites)
97
+ - **Rules Sync** — Scan → Deduplicate → Conflict detection → Cross-format generation
98
+ - **Skills & Workflows** — Copy skill folders and workflow files across agents
99
+ - **Apply with Safety** — Backup `.bak` → Atomic write → Auto-rollback on failure
65
100
 
66
- ### Context Continuity
101
+ ### 🪝 Auto-Memory Hooks
67
102
 
68
- - **Session Start**: Agent rules instruct AI to search memories before responding
69
- - **During Session**: Auto-capture decisions, bugs, gotchas via hooks + agent-driven `memorix_store`
70
- - **Session End**: Agent stores a "handoff note" summarizing progress and next steps
71
- - **Result**: Start a new session and your AI already knows everything — no re-explaining needed
103
+ - **Implicit Memory** — Auto-captures decisions, errors, gotchas from agent activity
104
+ - **Multi-Language Pattern Detection** — English + Chinese keyword matching
105
+ - **Cooldown & Noise Filtering** — 30s cooldown, skips trivial commands (ls, cat, pwd)
106
+ - **One-Command Install** — `memorix hooks install` sets up hooks + rules for your agent
72
107
 
73
- ### P5 — Intelligence (Competitor-Inspired)
108
+ ### 🔁 Context Continuity
74
109
 
75
- - **Access Tracking**: `accessCount` + `lastAccessedAt` on every search hit (from mcp-memory-service)
76
- - **Memory Decay**: Exponential decay scoring `score = importance × e^(-age/retention) × accessBoost` (from mcp-memory-service)
77
- - **Retention Lifecycle**: Active → Stale → Archive-candidate with immunity rules (from MemCP)
78
- - **Entity Extraction**: Auto-extract files, modules, URLs, CamelCase identifiers from narratives (from MemCP)
79
- - **Auto-Enrichment**: `memorix_store` automatically enriches concepts and filesModified
80
- - **Causal Detection**: Detects "because/due to/caused by" patterns for typed relations
81
- - **Auto-Relations**: Implicit Knowledge Graph relation creation on store (causes/fixes/modifies)
82
- - **Typed Relations**: Recommended types: causes, fixes, supports, opposes, contradicts, depends_on
110
+ ```
111
+ Session 1: You and AI discuss auth architecture
112
+ → Memorix auto-stores the decision
83
113
 
84
- ## Quick Start
114
+ Session 2: New chat, same project
115
+ → AI searches Memorix → "Ah, we decided on JWT with refresh tokens"
116
+ → No re-explaining needed!
117
+ ```
85
118
 
86
- ### Install
119
+ ---
87
120
 
88
- ```bash
89
- npm install -g memorix
90
- ```
121
+ ## 🔧 Agent Configuration
91
122
 
92
- ### Configure in your agent
123
+ ### Cursor
93
124
 
94
- **Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
125
+ `.cursor/mcp.json`:
95
126
  ```json
96
127
  {
97
128
  "mcpServers": {
98
129
  "memorix": {
99
- "command": "memorix",
100
- "args": ["serve"]
130
+ "command": "npx",
131
+ "args": ["-y", "memorix@latest", "serve"]
101
132
  }
102
133
  }
103
134
  }
104
135
  ```
105
136
 
106
- **Cursor** (`.cursor/mcp.json`):
107
- ```json
108
- {
109
- "mcpServers": {
110
- "memorix": {
111
- "command": "memorix",
112
- "args": ["serve"]
113
- }
114
- }
115
- }
116
- ```
137
+ ### Claude Code
117
138
 
118
- **Claude Code** (`~/.claude.json`):
139
+ `~/.claude.json`:
119
140
  ```json
120
141
  {
121
142
  "mcpServers": {
122
143
  "memorix": {
123
- "command": "memorix",
124
- "args": ["serve"]
144
+ "command": "npx",
145
+ "args": ["-y", "memorix@latest", "serve"]
125
146
  }
126
147
  }
127
148
  }
128
149
  ```
129
150
 
130
- **Codex** (`~/.codex/config.toml`):
151
+ ### Codex
152
+
153
+ `~/.codex/config.toml`:
131
154
  ```toml
132
155
  [mcp_servers.memorix]
133
- command = "memorix"
134
- args = ["serve"]
156
+ command = "npx"
157
+ args = ["-y", "memorix@latest", "serve"]
135
158
  ```
136
159
 
137
- **VS Code Copilot** (VS Code `settings.json` or `.vscode/mcp.json`):
160
+ ### VS Code Copilot
161
+
162
+ `.vscode/mcp.json` or VS Code `settings.json`:
138
163
  ```json
139
164
  {
140
165
  "mcp": {
141
166
  "servers": {
142
167
  "memorix": {
143
- "command": "memorix",
144
- "args": ["serve"]
168
+ "command": "npx",
169
+ "args": ["-y", "memorix@latest", "serve"]
145
170
  }
146
171
  }
147
172
  }
148
173
  }
149
174
  ```
150
175
 
151
- ### Available MCP Tools
176
+ ### Antigravity
177
+
178
+ `~/.gemini/antigravity/settings/mcp_config.json`:
179
+ ```json
180
+ {
181
+ "mcpServers": {
182
+ "memorix": {
183
+ "command": "npx",
184
+ "args": ["-y", "memorix@latest", "serve"]
185
+ }
186
+ }
187
+ }
188
+ ```
189
+
190
+ ---
191
+
192
+ ## 🛠 Available MCP Tools
152
193
 
153
- #### Memorix Extensions (Progressive Disclosure)
194
+ ### Memorix Extensions
154
195
 
155
- | Tool | Layer | Description | Tokens |
156
- |------|-------|-------------|--------|
157
- | `memorix_store` | Write | Store observation with auto-enrichment | — |
158
- | `memorix_search` | L1 | Compact index search (hybrid if fastembed) | ~50-100/result |
159
- | `memorix_timeline` | L2 | Chronological context | ~200/group |
160
- | `memorix_detail` | L3 | Full observation details | ~500-1000/result |
161
- | `memorix_retention` | Analytics | Memory decay & retention status | — |
162
- | `memorix_rules_sync` | Rules | Scan, dedup, convert rules across agents | — |
163
- | `memorix_workspace_sync` | Workspace | Scan/migrate MCP configs, workflows, and skills across agents | — |
196
+ | Tool | Purpose | Token Cost |
197
+ |------|---------|------------|
198
+ | `memorix_store` | Store observation with auto-enrichment | — |
199
+ | `memorix_search` | L1: Compact index search | ~50-100/result |
200
+ | `memorix_timeline` | L2: Chronological context | ~100-200/group |
201
+ | `memorix_detail` | L3: Full observation details | ~500-1000/result |
202
+ | `memorix_retention` | Memory decay & retention dashboard | — |
203
+ | `memorix_rules_sync` | Scan/deduplicate/generate rules across agents | — |
204
+ | `memorix_workspace_sync` | Migrate MCP configs, workflows, skills | — |
164
205
 
165
- #### MCP Official Compatible
206
+ ### MCP Official Compatible (Drop-in Replacement)
166
207
 
167
- | Tool | Description |
168
- |------|-------------|
208
+ | Tool | Purpose |
209
+ |------|---------|
169
210
  | `create_entities` | Create knowledge graph entities |
170
211
  | `create_relations` | Create relations between entities |
171
212
  | `add_observations` | Add observations to entities |
@@ -176,101 +217,165 @@ args = ["serve"]
176
217
  | `open_nodes` | Get entities by name |
177
218
  | `read_graph` | Read entire graph |
178
219
 
179
- ## Architecture
220
+ ---
221
+
222
+ ## 🧩 How It Works
223
+
224
+ ### Data Flow
180
225
 
181
226
  ```
182
- ┌─────────────────────────────────────────────┐
183
- │ MCP Clients │
184
- │ Windsurf│Cursor│Claude Code│Codex│Copilot │
185
- └──────────────────┬──────────────────────────┘
186
- │ stdio
187
- ┌──────────────────▼──────────────────────────┐
188
- │ Memorix MCP Server │
189
- │ │
190
- │ ┌────────────┐ ┌─────────────────────┐ │
191
- │ │ Knowledge │ │ Compact Engine │ │
192
- │ │ Graph Mgr │ │ (3-layer search) │ │
193
- │ └─────┬──────┘ └──────────┬──────────┘ │
194
- │ │ │ │
195
- │ ┌─────▼────────────────────▼──────────┐ │
196
- │ │ Orama Store │ │
197
- │ │ (full-text + vector search) │ │
198
- │ └─────────────────┬──────────────────┘ │
199
- │ │ │
200
- │ ┌─────────────────▼──────────────────┐ │
201
- │ │ Persistence Layer │ │
202
- │ │ (JSONL + JSON per project) │ │
203
- │ └─────────────────────────────────────┘ │
204
- │ │
205
- │ ┌────────────────────────────────────┐ │
206
- │ │ Rules & Skills Syncer │ │
207
- │ │ Cursor│Claude Code│Codex│Windsurf│Copilot│ │
208
- │ │ rules: scan→dedup→conflict→gen │ │
209
- │ │ skills: scan→copy (no convert) │ │
210
- │ └────────────────────────────────────┘ │
211
- │ │
212
- │ ┌────────────────────────────────────┐ │
213
- │ │ Auto-Memory Hooks │ │
214
- │ │ normalize→detect→filter→store │ │
215
- │ │ + agent rules (context cont.) │ │
216
- │ └────────────────────────────────────┘ │
217
- └──────────────────────────────────────────────┘
227
+ Agent ──memorix_store──▶ Entity Extractor ──▶ Auto-Relations ──▶ Knowledge Graph
228
+ │ │
229
+ ▼ │
230
+ Orama Index ◀───────── Persistence Layer ◀───┘
231
+ (BM25 + Vector) (~/.memorix/data/<project>/)
232
+ │
233
+ Agent ◀──memorix_search──┘ L1: Compact Index (~50-100 tokens)
234
+ Agent ◀──memorix_timeline─ L2: Timeline Context
235
+ Agent ◀──memorix_detail─── L3: Full Details (~500-1000 tokens)
218
236
  ```
219
237
 
220
- ## Tech Stack
238
+ ### Progressive Disclosure Example
221
239
 
222
- | Component | Library | Source |
223
- |-----------|---------|--------|
224
- | MCP Server | `@modelcontextprotocol/sdk` | Official SDK |
225
- | Search | `@orama/orama` | Full-text + Vector + Hybrid |
226
- | Embeddings | `fastembed` (optional) | Local ONNX, zero API calls |
227
- | Token counting | `gpt-tokenizer` | — |
228
- | Data model | Entity-Relation-Observation | MCP Official Memory Server |
229
- | Compact strategy | 3-layer Progressive Disclosure | claude-mem |
230
- | Memory decay | Exponential decay + retention | mcp-memory-service + MemCP |
231
- | Entity extraction | Regex patterns | MemCP |
232
- | Rule parsing | `gray-matter` | — |
233
- | Build | `tsup` | — |
234
- | Test | `vitest` | 219 tests |
240
+ ```
241
+ 🔍 Agent calls memorix_search("auth bug")
242
+
243
+ 📋 L1 Response (compact — agent scans IDs):
244
+ | ID | Time | T | Title | Tokens |
245
+ |-----|---------|-----|--------------------------|--------|
246
+ | #42 | 2:14 PM | 🟡 | Fixed JWT refresh timeout | ~155 |
247
+ | #38 | 1:30 PM | 🔵 | How JWT refresh works | ~220 |
248
+
249
+ 🔎 Agent calls memorix_detail([42])
250
+
251
+ 📄 L3 Response (full content):
252
+ # Observation #42 — Fixed JWT refresh timeout
253
+ Type: 🟡 problem-solution | Entity: auth-module
254
+ Narrative: The JWT refresh token was timing out after 15 minutes
255
+ because the expiry was hardcoded. Fixed by reading from env...
256
+ Facts: ["Default timeout: 60s", "Fix: use REFRESH_TTL env var"]
257
+ Files: ["src/auth/jwt.ts", "src/config.ts"]
258
+ ```
259
+
260
+ ### Architecture
261
+
262
+ ```
263
+ ┌──────────────────────────────────────────────────────────────┐
264
+ │ AI Coding Agents │
265
+ │ Windsurf │ Cursor │ Claude Code │ Codex │ Copilot │ Antigravity
266
+ └────────────────────────┬─────────────────────────────────────┘
267
+ │ MCP Protocol (stdio)
268
+ ┌────────────────────────▼─────────────────────────────────────┐
269
+ │ Memorix MCP Server (16 tools) │
270
+ │ │
271
+ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
272
+ │ │ Memory │ │ Compact │ │ Workspace Sync │ │
273
+ │ │ Layer │ │ Engine │ │ (6 adapters) │ │
274
+ │ │ │ │ (3-layer) │ │ │ │
275
+ │ │ • Graph │ │ │ │ • MCP Configs │ │
276
+ │ │ • Retention │ │ │ │ • Rules │ │
277
+ │ │ • Entities │ │ │ │ • Skills │ │
278
+ │ │ • Relations │ │ │ │ • Workflows │ │
279
+ │ └──────┬──────┘ └──────┬───────┘ └──────────────────┘ │
280
+ │ │ │ │
281
+ │ ┌──────▼────────────────▼───────────────────────────────┐ │
282
+ │ │ Orama Store (BM25 + Vector) │ Persistence (JSONL) │ │
283
+ │ └───────────────────────────────────────────────────────┘ │
284
+ │ │
285
+ │ ┌───────────────────────────────────────────────────────┐ │
286
+ │ │ Hooks System: Normalizer → Pattern Detector → Store │ │
287
+ │ │ (Auto-captures decisions, bugs, gotchas from agents) │ │
288
+ │ └───────────────────────────────────────────────────────┘ │
289
+ └──────────────────────────────────────────────────────────────┘
290
+ ```
235
291
 
236
- ## Optional: Enable Vector Search
292
+ ---
293
+
294
+ ## 🔮 Optional: Vector Search
237
295
 
238
296
  Install `fastembed` for hybrid (BM25 + semantic) search:
239
297
 
240
298
  ```bash
241
- npm install fastembed
299
+ npm install -g fastembed
242
300
  ```
243
301
 
244
- Without it, Memorix uses BM25 full-text search (already very effective for code memories). With it, queries like "authentication" will also match observations containing "login flow".
302
+ - **Without it** — BM25 full-text search (already very effective for code)
303
+ - **With it** — Queries like "authentication" also match "login flow" via semantic similarity
304
+ - Local ONNX inference, zero API calls, zero privacy risk
305
+
306
+ ---
245
307
 
246
- ## Development
308
+ ## 💾 Data Storage
309
+
310
+ All data is stored locally per project:
311
+
312
+ ```
313
+ ~/.memorix/data/<projectId>/
314
+ ├── observations.json # Structured observations
315
+ ├── id-counter.txt # Next observation ID
316
+ ├── entities.jsonl # Knowledge graph nodes (MCP compatible)
317
+ └── relations.jsonl # Knowledge graph edges (MCP compatible)
318
+ ```
319
+
320
+ - `projectId` is auto-detected from Git remote URL (e.g., `user/repo`)
321
+ - Data is shared across all agents (same directory)
322
+ - No cloud, no API keys, no external services
323
+
324
+ ---
325
+
326
+ ## 🧑‍💻 Development
247
327
 
248
328
  ```bash
249
- # Install dependencies
329
+ git clone https://github.com/AVIDS2/memorix.git
330
+ cd memorix
250
331
  npm install
251
332
 
252
- # Build
253
- npm run build
254
-
255
- # Run tests (219 tests)
256
- npm test
333
+ npm run dev # tsup watch mode
334
+ npm test # vitest (274 tests)
335
+ npm run lint # TypeScript type check
336
+ npm run build # Production build
337
+ ```
257
338
 
258
- # Type check
259
- npm run lint
339
+ ### Project Structure
260
340
 
261
- # Watch mode
262
- npm run dev
263
341
  ```
342
+ src/
343
+ ├── server.ts # MCP Server entry (16 tools)
344
+ ├── types.ts # All type definitions
345
+ ├── memory/ # Graph, observations, retention, entity extraction
346
+ ├── store/ # Orama search engine + disk persistence
347
+ ├── compact/ # 3-layer Progressive Disclosure engine
348
+ ├── embedding/ # Optional fastembed vector provider
349
+ ├── hooks/ # Auto-memory hooks (normalizer + pattern detector)
350
+ ├── workspace/ # Cross-agent MCP/workflow/skills sync
351
+ ├── rules/ # Cross-agent rules sync (6 adapters)
352
+ ├── project/ # Git-based project detection
353
+ └── cli/ # CLI commands (serve, hook, sync, status)
354
+ ```
355
+
356
+ > 📚 Full documentation available in [`docs/`](./docs/) — architecture, modules, API reference, design decisions, and more.
357
+
358
+ ---
264
359
 
265
- ## Acknowledgements
360
+ ## 🙏 Acknowledgements
266
361
 
267
362
  Memorix stands on the shoulders of these excellent projects:
268
363
 
269
364
  - [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) — Hybrid search, exponential decay, access tracking
270
- - [MemCP](https://github.com/maydali28/memcp) — MAGMA 4-graph, entity extraction, retention lifecycle, token budget
271
- - [claude-mem](https://github.com/anthropics/claude-code) — 3-layer Progressive Disclosure, lifecycle hooks
365
+ - [MemCP](https://github.com/maydali28/memcp) — MAGMA 4-graph, entity extraction, retention lifecycle
366
+ - [claude-mem](https://github.com/anthropics/claude-code) — 3-layer Progressive Disclosure
272
367
  - [Mem0](https://github.com/mem0ai/mem0) — Memory layer architecture patterns
273
368
 
274
- ## License
369
+ ---
370
+
371
+ ## 📄 License
275
372
 
276
373
  Apache 2.0 — see [LICENSE](LICENSE)
374
+
375
+ ---
376
+
377
+ <p align="center">
378
+ <strong>Made with ❤️ by <a href="https://github.com/AVIDS2">AVIDS2</a></strong>
379
+ <br>
380
+ <sub>If Memorix helps your workflow, consider giving it a ⭐ on GitHub!</sub>
381
+ </p>