Update README.md with smart injection and real embeddings

README.md

@@ -2,6 +2,7 @@
 license: mit
 library_name: mnemo
 tags:
+  - mnemo
   - memory
   - ai-memory
   - llm-memory
@@ -16,6 +17,8 @@ tags:
   - mem0
   - vector-search
   - knowledge-graph
+  - smart-injection
+  - context-check
 pipeline_tag: feature-extraction
 ---
 
@@ -23,41 +26,203 @@ pipeline_tag: feature-extraction
 
 **Open-source memory for LLMs, chatbots, and AI agents**
 
-## Install
+> 21x faster than mem0 • Smart memory injection • Real embeddings • No API keys
+
+## ✨ What's New in v2.0
+
+- **🎯 Smart Memory Injection** - Context-check algorithm with 90% accuracy decides WHEN to inject memory
+- **🧬 Real Embeddings** - sentence-transformers support (with hash fallback)
+- **📊 Benchmark Tested** - Validated on medical AI bias detection tasks
+
+## 📦 Install
 
 ```bash
 pip install mnemo-memory
 ```
 
-## Quick Start
+Or with all features:
+```bash
+pip install mnemo-memory[all]  # Includes sentence-transformers, faiss-cpu
+```
+
+## 🚀 Quick Start
 
 ```python
 from mnemo import Mnemo
 
 memory = Mnemo()
-memory.add("User prefers Python")
-results = memory.search("preferences")  # 0.27ms!
+memory.add("User prefers Python and dark mode")
+memory.add("Project deadline is March 15th")
+
+# Search memories
+results = memory.search("user preferences")
+print(results[0].content)  # "User prefers Python and dark mode"
+```
+
+## 🎯 Smart Memory Injection (NEW!)
+
+Don't inject memory blindly - use context-check to decide when it helps:
+
+```python
+from mnemo import Mnemo
+
+m = Mnemo()
+m.add("Previous analysis showed gender bias patterns")
+m.add("Framework has 5 checkpoints for detection")
+
+# Check if query needs memory
+query1 = "What is machine learning?"
+query2 = "Based on your previous analysis, explain the patterns"
+
+m.should_inject(query1)  # False - standalone question
+m.should_inject(query2)  # True - references prior context
+
+# Get formatted context for injection
+if m.should_inject(query2):
+    context = m.get_context("previous analysis")
+    prompt = f"{context}\n\nQuestion: {query2}"
 ```
 
-## MCP Server (for Claude)
+### When Memory Helps vs Hurts
+
+| Query Type | Example | Action |
+|------------|---------|--------|
+| References prior | "Based on your previous analysis..." | ✓ Inject |
+| Comparison | "Compare this to earlier findings" | ✓ Inject |
+| Synthesis | "Synthesize all the patterns" | ✓ Inject |
+| Standalone | "What is Python?" | ✗ Skip |
+| New topic | "This is a NEW problem..." | ✗ Skip |
+
+## 🔬 Benchmark Results
+
+Tested on NRA-19 Medical AI Bias Detection benchmark:
+
+### Memory Injection Strategy Comparison
+
+| Strategy | Score | Decision Accuracy |
+|----------|-------|-------------------|
+| Always inject | 47/100 | 70% |
+| **Context-check** | **46/100** | **90%** |
+| Never inject | 41/100 | 30% |
+| Similarity only | 37/100 | 50% |
+
+### Embedding Comparison
+
+| Type | Score | vs Baseline |
+|------|-------|-------------|
+| No memory | 77/100 | — |
+| Hash embeddings | 65/100 | -12 pts ❌ |
+| **Real embeddings** | **74/100** | **-3 pts** |
+
+**Key finding:** Real embeddings are 9 points better than hash embeddings.
+
+## 🔧 MCP Server (for Claude)
+
+Add to your Claude config:
 
 ```json
 {
   "mcpServers": {
-    "mnemo": {"command": "uvx", "args": ["mnemo-memory"]}
+    "mnemo": {
+      "command": "uvx",
+      "args": ["mnemo-memory"]
+    }
   }
 }
 ```
 
-## Benchmarks vs mem0
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `add_memory` | Store a new memory |
+| `search_memory` | Search stored memories |
+| `should_inject` | Check if memory should be used |
+| `get_context` | Get formatted context for injection |
+| `get_stats` | Get system statistics |
+
+## 📊 Benchmarks vs mem0
 
 | Metric | mem0 | Mnemo |
 |--------|------|-------|
-| Search | 5.73ms | **0.27ms** |
-| API Keys | Required | **None** |
-| Offline | No | **Yes** |
+| Search latency | 5.73ms | **0.27ms** |
+| API keys required | Yes | **No** |
+| Works offline | No | **Yes** |
+| Smart injection | No | **Yes** |
+| Embedding options | API only | **Local + API** |
+
+## 🏗️ Architecture
 
-## Links
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Mnemo                                │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │  Semantic   │  │    BM25     │  │   Graph     │         │
+│  │   Search    │  │   Search    │  │   Search    │         │
+│  │  (FAISS)    │  │ (Keywords)  │  │ (NetworkX)  │         │
+│  └──────┬──────┘  └──────┬───��──┘  └──────┬──────┘         │
+│         │                │                │                 │
+│         └────────────────┴────────────────┘                 │
+│                          │                                  │
+│                   ┌──────┴──────┐                           │
+│                   │   Ranker    │ ← Feedback Learning       │
+│                   └──────┬──────┘                           │
+│                          │                                  │
+│              ┌───────────┴───────────┐                      │
+│              │  Smart Injection      │                      │
+│              │  (Context-Check)      │                      │
+│              └───────────────────────┘                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 📝 API Reference
 
-- [Demo](https://huggingface.co/spaces/AthelaPerk/mnemo)
+### Mnemo Class
+
+```python
+class Mnemo:
+    def __init__(
+        self,
+        embedding_model: str = "all-MiniLM-L6-v2",
+        embedding_dim: int = 384,
+        semantic_weight: float = 0.5,
+        bm25_weight: float = 0.3,
+        graph_weight: float = 0.2,
+        use_real_embeddings: bool = True
+    )
+    
+    def add(content: str, metadata: dict = None) -> str
+    def search(query: str, top_k: int = 5) -> List[SearchResult]
+    def should_inject(query: str, context: str = "") -> bool
+    def get_context(query: str, top_k: int = 3) -> str
+    def feedback(query: str, memory_id: str, relevance: float)
+    def get_stats() -> dict
+    def clear()
+```
+
+### SearchResult
+
+```python
+@dataclass
+class SearchResult:
+    id: str
+    content: str
+    score: float
+    strategy_scores: Dict[str, float]
+    metadata: Dict
+```
+
+## 🔗 Links
+
+- [Demo Space](https://huggingface.co/spaces/AthelaPerk/mnemo)
 - [MCP Server](https://huggingface.co/spaces/AthelaPerk/mnemo-mcp)
+- [GitHub Issues](https://github.com/AthelaPerk/mnemo/issues)
+
+## 📄 License
+
+MIT License - Use freely in your projects!
+
+---
+
+Built with ❤️ for the AI community