memorix 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.1.0 (2026-02-14)
+
+### Core
+- Knowledge Graph: Entity-Relation-Observation model (MCP Official compatible)
+- 3-Layer Progressive Disclosure: compact search → timeline → detail
+- 9 observation types with icon classification
+- Full-text search via Orama (BM25)
+- Per-project isolation via Git remote detection
+- 14 MCP tools (9 official + 5 Memorix extensions)
+
+### Cross-Agent Sync
+- Rules Parser: 4 format adapters (Cursor, Claude Code, Codex, Windsurf)
+- Rules Syncer: scan → deduplicate → conflict detection → cross-format generation
+- Workspace Sync: MCP config migration + workflow sync + apply with backup/rollback
+
+### Intelligence (Competitor-Inspired)
+- Access tracking: accessCount + lastAccessedAt (from mcp-memory-service)
+- Token budget: maxTokens search trimming (from MemCP)
+- Memory decay: exponential decay + retention lifecycle + immunity (from mcp-memory-service + MemCP)
+- Entity extraction: regex-based file/module/URL/CamelCase extraction (from MemCP)
+- Auto-enrichment: memorix_store auto-extracts and enriches concepts/files
+- Causal detection: "because/due to/caused by" pattern detection
+- Auto-relations: implicit Knowledge Graph relation creation (causes/fixes/modifies)
+- Retention status: memorix_retention MCP tool
+
+### Vector Search
+- Embedding provider abstraction layer (extensible)
+- fastembed integration (optional, local ONNX, 384-dim bge-small)
+- Orama hybrid search mode (BM25 + vector)
+- Graceful degradation: no fastembed → fulltext only
+- Embedding cache (5000 entries LRU)
+
+### Agent Instructions
+- CLAUDE.md: Claude Code usage instructions + lifecycle hooks
+- Example configs for Cursor, Windsurf, Codex

package/CLAUDE.md

@@ -0,0 +1,47 @@
+# 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_retention` | Check memory health | `action: "summary"` |
+| `memorix_rules_sync` | Sync agent rules | `action: "status"` |
+| `memorix_workspace_sync` | Migrate workspace configs | `action: "scan"` |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Memorix Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# Memorix — Cross-Agent Memory Bridge
+
+> Universal memory layer for AI coding agents via MCP
+
+## What is Memorix?
+
+Memorix is a lightweight local MCP server that acts as a **universal memory layer** across AI coding agents. Your knowledge from Cursor, Claude Code, Codex, and Windsurf is stored once and shared everywhere.
+
+### The Problem
+
+- claude-mem only serves Claude Code
+- memU only serves OpenClaw
+- Your architecture decisions in Cursor are invisible to Claude Code
+- Bug fix knowledge in Windsurf doesn't transfer to Codex
+- **No one does cross-agent memory**
+
+### The Solution
+
+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.
+
+## Features
+
+### P0 — Core (Current)
+
+- **Knowledge Graph**: Entity-Relation model (MCP Official Memory Server compatible)
+- **3-Layer Progressive Disclosure**: Token-efficient search (claude-mem pattern)
+  - L1: Compact index (~50-100 tokens/result)
+  - L2: Timeline context
+  - L3: Full details on demand (~500-1000 tokens/result)
+- **9 Observation Types**: 🎯🔴🟡🔵🟢🟣🟠🟤⚖️
+- **Full-text Search**: Powered by Orama
+- **Per-project Isolation**: Auto-detected via Git remote
+- **MCP Compatible**: All 9 official Memory Server tools + 5 Memorix extensions
+
+### P1 — Smart Search
+
+- **Hybrid Search**: Full-text (BM25) + Vector (semantic) via Orama
+- **Vector Embeddings**: Optional `fastembed` (local ONNX, zero API calls)
+- **Graceful Degradation**: No fastembed? Falls back to BM25 fulltext automatically
+- **Token Budget**: `maxTokens` parameter trims results to fit context windows
+
+### P2 — Cross-Agent Sync
+
+- **Rules Parser**: 4 format adapters (Cursor `.mdc`, Claude Code `CLAUDE.md`, Codex `SKILL.md`, Windsurf `.windsurfrules`)
+- **Rules Syncer**: Scan → Deduplicate → Conflict detection → Cross-format generation
+- **Workspace Sync**: MCP config migration + workflow sync across agents
+- **Apply with Safety**: Backup → Atomic write → Auto-rollback on failure
+
+### P5 — Intelligence (Competitor-Inspired)
+
+- **Access Tracking**: `accessCount` + `lastAccessedAt` on every search hit (from mcp-memory-service)
+- **Memory Decay**: Exponential decay scoring `score = importance × e^(-age/retention) × accessBoost` (from mcp-memory-service)
+- **Retention Lifecycle**: Active → Stale → Archive-candidate with immunity rules (from MemCP)
+- **Entity Extraction**: Auto-extract files, modules, URLs, CamelCase identifiers from narratives (from MemCP)
+- **Auto-Enrichment**: `memorix_store` automatically enriches concepts and filesModified
+- **Causal Detection**: Detects "because/due to/caused by" patterns for typed relations
+- **Auto-Relations**: Implicit Knowledge Graph relation creation on store (causes/fixes/modifies)
+- **Typed Relations**: Recommended types: causes, fixes, supports, opposes, contradicts, depends_on
+
+## Quick Start
+
+### Install
+
+```bash
+npm install memorix
+```
+
+### Configure in your agent
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "node",
+      "args": ["node_modules/memorix/dist/index.js"]
+    }
+  }
+}
+```
+
+**Claude Code** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "node",
+      "args": ["node_modules/memorix/dist/index.js"]
+    }
+  }
+}
+```
+
+**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
+```json
+{
+  "mcpServers": {
+    "memorix": {
+      "command": "node",
+      "args": ["node_modules/memorix/dist/index.js"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+#### Memorix Extensions (Progressive Disclosure)
+
+| Tool | Layer | Description | Tokens |
+|------|-------|-------------|--------|
+| `memorix_store` | Write | Store observation with auto-enrichment | — |
+| `memorix_search` | L1 | Compact index search (hybrid if fastembed) | ~50-100/result |
+| `memorix_timeline` | L2 | Chronological context | ~200/group |
+| `memorix_detail` | L3 | Full observation details | ~500-1000/result |
+| `memorix_retention` | Analytics | Memory decay & retention status | — |
+| `memorix_rules_sync` | Rules | Scan, dedup, convert rules across agents | — |
+| `memorix_workspace_sync` | Workspace | Scan/migrate MCP configs across agents | — |
+
+#### MCP Official Compatible
+
+| Tool | Description |
+|------|-------------|
+| `create_entities` | Create knowledge graph entities |
+| `create_relations` | Create relations between entities |
+| `add_observations` | Add observations to entities |
+| `delete_entities` | Delete entities (cascades relations) |
+| `delete_observations` | Delete specific observations |
+| `delete_relations` | Delete relations |
+| `search_nodes` | Search knowledge graph |
+| `open_nodes` | Get entities by name |
+| `read_graph` | Read entire graph |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│                 MCP Clients                  │
+│   Cursor │ Claude Code │ Codex │ Windsurf   │
+└──────────────────┬──────────────────────────┘
+                   │ stdio
+┌──────────────────▼──────────────────────────┐
+│              Memorix MCP Server              │
+│                                              │
+│  ┌────────────┐  ┌─────────────────────┐    │
+│  │ Knowledge  │  │  Compact Engine     │    │
+│  │ Graph Mgr  │  │  (3-layer search)   │    │
+│  └─────┬──────┘  └──────────┬──────────┘    │
+│        │                    │                │
+│  ┌─────▼────────────────────▼──────────┐    │
+│  │           Orama Store               │    │
+│  │    (full-text + vector search)      │    │
+│  └─────────────────┬──────────────────┘    │
+│                    │                        │
+│  ┌─────────────────▼──────────────────┐    │
+│  │         Persistence Layer           │    │
+│  │   (JSONL + JSON per project)        │    │
+│  └─────────────────────────────────────┘    │
+│                                              │
+│  ┌────────────────────────────────────┐     │
+│  │         Rules Syncer               │     │
+│  │  Cursor│Claude│Codex│Windsurf     │     │
+│  │  scan → dedup → conflict → gen    │     │
+│  └────────────────────────────────────┘     │
+└──────────────────────────────────────────────┘
+```
+
+## Tech Stack
+
+| Component | Library | Source |
+|-----------|---------|--------|
+| MCP Server | `@modelcontextprotocol/sdk` | Official SDK |
+| Search | `@orama/orama` | Full-text + Vector + Hybrid |
+| Embeddings | `fastembed` (optional) | Local ONNX, zero API calls |
+| Token counting | `gpt-tokenizer` | — |
+| Data model | Entity-Relation-Observation | MCP Official Memory Server |
+| Compact strategy | 3-layer Progressive Disclosure | claude-mem |
+| Memory decay | Exponential decay + retention | mcp-memory-service + MemCP |
+| Entity extraction | Regex patterns | MemCP |
+| Rule parsing | `gray-matter` | — |
+| Build | `tsup` | — |
+| Test | `vitest` | 195 tests |
+
+## Optional: Enable Vector Search
+
+Install `fastembed` for hybrid (BM25 + semantic) search:
+
+```bash
+npm install fastembed
+```
+
+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".
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests (195 tests)
+npm test
+
+# Type check
+npm run lint
+
+# Watch mode
+npm run dev
+```
+
+## Acknowledgements
+
+Memorix stands on the shoulders of these excellent projects:
+
+- [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) — Hybrid search, exponential decay, access tracking
+- [MemCP](https://github.com/maydali28/memcp) — MAGMA 4-graph, entity extraction, retention lifecycle, token budget
+- [claude-mem](https://github.com/anthropics/claude-code) — 3-layer Progressive Disclosure, lifecycle hooks
+- [Mem0](https://github.com/mem0ai/mem0) — Memory layer architecture patterns
+
+## License
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }