memorix 0.10.2 → 0.10.3

package/README.md

@@ -14,7 +14,7 @@
   <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-534%20passed-brightgreen?style=flat-square" alt="tests">
+  <img src="https://img.shields.io/badge/tests-593%20passed-brightgreen?style=flat-square" alt="tests">
 </p>
 
 <p align="center">
@@ -169,17 +169,39 @@ Captures decisions, errors, and gotchas automatically. Pattern detection in Engl
 
 ### Hybrid Search
 
-BM25 fulltext out of the box (~50MB RAM). Semantic search is **opt-in** to minimize resource usage:
+BM25 fulltext out of the box (~50MB RAM). Semantic search is **opt-in** — 3 providers:
 
 ```bash
-# Enable semantic search (optional — requires 300-500MB RAM)
-# Set in your MCP config env, or export before starting:
-MEMORIX_EMBEDDING=fastembed    # ONNX, fastest (~300MB)
-MEMORIX_EMBEDDING=transformers # Pure JS (~500MB)
-MEMORIX_EMBEDDING=off          # Default — BM25 only, minimal resources
+# Set in your MCP config env:
+MEMORIX_EMBEDDING=api           # ⭐ Recommended — zero local RAM, best quality
+MEMORIX_EMBEDDING=fastembed     # Local ONNX (~300MB RAM)
+MEMORIX_EMBEDDING=transformers  # Local JS/WASM (~500MB RAM)
+MEMORIX_EMBEDDING=off           # Default — BM25 only, minimal resources
 ```
 
-Install the provider you chose:
+#### API Embedding (Recommended)
+
+Works with any OpenAI-compatible endpoint — OpenAI, Qwen, Cohere, 中转站/反代, Ollama:
+
+```bash
+MEMORIX_EMBEDDING=api
+MEMORIX_EMBEDDING_API_KEY=sk-xxx              # or reuse OPENAI_API_KEY
+MEMORIX_EMBEDDING_MODEL=text-embedding-3-small # default
+MEMORIX_EMBEDDING_BASE_URL=https://api.openai.com/v1  # optional
+MEMORIX_EMBEDDING_DIMENSIONS=512              # optional dimension shortening
+```
+
+**Performance advantages over competitors:**
+- **10K LRU cache + disk persistence** — repeat queries cost $0 and take 0ms
+- **Batch API calls** — up to 2048 texts per request (competitors: 1-by-1)
+- **4x concurrent processing** — parallel batch chunks
+- **Text normalization** — better cache hit rates via whitespace dedup
+- **Debounced disk writes** — 5s coalesce window, not per-call I/O
+- **Zero external dependencies** — no Chroma, no SQLite, just native `fetch`
+- **Smart key fallback** — auto-reuses LLM API key if same provider
+
+#### Local Embedding
+
 ```bash
 npm install -g fastembed              # for MEMORIX_EMBEDDING=fastembed
 npm install -g @huggingface/transformers  # for MEMORIX_EMBEDDING=transformers
@@ -187,6 +209,36 @@ npm install -g @huggingface/transformers  # for MEMORIX_EMBEDDING=transformers
 
 Both run 100% locally. Zero API calls.
 
+### LLM Enhanced Mode (Optional)
+
+Enable intelligent memory deduplication and fact extraction with your own API key:
+
+```bash
+# Set in your MCP config env, or export before starting:
+MEMORIX_LLM_API_KEY=sk-xxx          # OpenAI-compatible API key
+MEMORIX_LLM_PROVIDER=openai         # openai | anthropic | openrouter
+MEMORIX_LLM_MODEL=gpt-4o-mini       # model name
+MEMORIX_LLM_BASE_URL=https://...    # custom endpoint (optional)
+```
+
+Or use existing env vars — Memorix auto-detects:
+- `OPENAI_API_KEY` → OpenAI
+- `ANTHROPIC_API_KEY` → Anthropic  
+- `OPENROUTER_API_KEY` → OpenRouter
+
+**Without LLM**: Free heuristic deduplication (similarity-based)  
+**With LLM**: Smart merge, fact extraction, contradiction detection
+
+### Interactive CLI
+
+```bash
+memorix              # Interactive menu (no args)
+memorix configure    # LLM + Embedding provider setup (TUI)
+memorix status       # Project info + stats
+memorix dashboard    # Web UI at localhost:3210
+memorix hooks install # Auto-capture for IDEs
+```
+
 ---
 
 ## How It Works
@@ -222,23 +274,6 @@ Both run 100% locally. Zero API calls.
 
 ---
 
-## Comparison
-
-| | [Mem0](https://github.com/mem0ai/mem0) | [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) | **Memorix** |
-|---|---|---|---|
-| **Agents** | SDK-based | 13+ (MCP) | **9 agents (MCP)** |
-| **Cross-agent workspace sync** | — | — | **MCP configs, rules, skills, workflows** |
-| **Knowledge graph** | — | Yes | **Yes (MCP Official compatible)** |
-| **Hybrid search** | — | Yes | **Yes (BM25 + vector)** |
-| **Token-efficient retrieval** | — | — | **3-layer progressive disclosure** |
-| **Auto-memory hooks** | — | — | **Yes (multi-language pattern detection)** |
-| **Memory decay** | — | Yes | **Yes (exponential + immunity)** |
-| **Web dashboard** | Cloud | Yes | **Yes (D3.js graph)** |
-| **Privacy** | Cloud | Local | **100% local** |
-| **Cost** | Per-call | $0 | **$0** |
-
----
-
 ## Development
 
 ```bash
@@ -246,7 +281,7 @@ git clone https://github.com/AVIDS2/memorix.git
 cd memorix && npm install
 
 npm run dev       # watch mode
-npm test          # 534 tests
+npm test          # 593 tests
 npm run build     # production build
 ```
 
@@ -260,6 +295,16 @@ npm run build     # production build
 
 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).
 
+## Star History
+
+<a href="https://star-history.com/#AVIDS2/memorix&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=AVIDS2/memorix&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=AVIDS2/memorix&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=AVIDS2/memorix&type=Date" width="600" />
+ </picture>
+</a>
+
 ## License
 
 [Apache 2.0](LICENSE)

package/README.zh-CN.md

@@ -14,7 +14,7 @@
   <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-534%20passed-brightgreen?style=flat-square" alt="tests">
+  <img src="https://img.shields.io/badge/tests-593%20passed-brightgreen?style=flat-square" alt="tests">
 </p>
 
 <p align="center">
@@ -212,23 +212,6 @@ npm install -g @huggingface/transformers   # 或: npm install -g fastembed
 
 ---
 
-## 对比
-
-| | [Mem0](https://github.com/mem0ai/mem0) | [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) | **Memorix** |
-|---|---|---|---|
-| **Agent 支持** | SDK 集成 | 13+（MCP） | **9 个 Agent（MCP）** |
-| **跨 Agent 工作区同步** | — | — | **MCP 配置、规则、技能、工作流** |
-| **知识图谱** | — | 是 | **是（兼容 MCP 官方）** |
-| **混合搜索** | — | 是 | **是（BM25 + 向量）** |
-| **Token 高效检索** | — | — | **3 层渐进式展示** |
-| **自动记忆 Hook** | — | — | **是（多语言模式检测）** |
-| **记忆衰减** | — | 是 | **是（指数衰减 + 豁免）** |
-| **Web 仪表盘** | 云端 | 是 | **是（D3.js 图谱）** |
-| **隐私** | 云端 | 本地 | **100% 本地** |
-| **费用** | 按量付费 | $0 | **$0** |
-
----
-
 ## 开发
 
 ```bash
@@ -236,7 +219,7 @@ git clone https://github.com/AVIDS2/memorix.git
 cd memorix && npm install
 
 npm run dev       # 监听模式
-npm test          # 534 个测试
+npm test          # 593 个测试
 npm run build     # 生产构建
 ```
 
@@ -250,6 +233,16 @@ npm run build     # 生产构建
 
 参考了 [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) 的设计思路。
 
+## Star History
+
+<a href="https://star-history.com/#AVIDS2/memorix&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=AVIDS2/memorix&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=AVIDS2/memorix&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=AVIDS2/memorix&type=Date" width="600" />
+ </picture>
+</a>
+
 ## 许可证
 
 [Apache 2.0](LICENSE)