Update README for v4.1 with decay feature and benchmarks

README.md

@@ -1,228 +1,76 @@
----
-license: mit
-library_name: mnemo
-tags:
-  - mnemo
-  - memory
-  - ai-memory
-  - llm-memory
-  - semantic-memory
-  - rag
-  - retrieval
-  - langchain
-  - llamaindex
-  - mcp
-  - agent-memory
-  - chatbot-memory
-  - mem0
-  - vector-search
-  - knowledge-graph
-  - smart-injection
-  - context-check
-pipeline_tag: feature-extraction
----
-
-# 🧠 Mnemo - AI Memory System
-
-**Open-source memory for LLMs, chatbots, and AI agents**
-
-> 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
-```
-
-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 and dark mode")
-memory.add("Project deadline is March 15th")
+# 🧠 Mnemo v4.1 - SLM-Inspired Memory System
 
-# Search memories
-results = memory.search("user preferences")
-print(results[0].content)  # "User prefers Python and dark mode"
-```
-
-## 🎯 Smart Memory Injection (NEW!)
+Memory augmentation library for LLMs based on the Semantic-Loop Memory architecture.
 
-Don't inject memory blindly - use context-check to decide when it helps:
+## Installation
 
 ```python
+# Download mnemo.py from this repo
 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}"
+mnemo = Mnemo()
+mnemo.add("User prefers Python for data analysis")
+results = mnemo.search("programming language")
 ```
 
-### 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:
+## Features
 
-### Memory Injection Strategy Comparison
+### Core
+- **Three-Tier Memory**: Working (50 items) → Token Loops → Semantic (persistent)
+- **Neural Links**: 8 link types with different creation thresholds and decay rates
+- **Memory Utility Predictor**: Decides WHEN to inject memory (90% accuracy)
+- **Self-Tuning**: Auto-adjusts thresholds based on feedback
 
-| Strategy | Score | Decision Accuracy |
-|----------|-------|-------------------|
-| Always inject | 47/100 | 70% |
-| **Context-check** | **46/100** | **90%** |
-| Never inject | 41/100 | 30% |
-| Similarity only | 37/100 | 50% |
+### v4.1 New
+- **Memory Decay**: Unused memories lose 1% quality per day
+- **Auto-Pruning**: Removes stale memories (quality < 0.15, unused > 30 days)
+- **Link Cleanup**: Orphaned links removed when memories are pruned
 
-### Embedding Comparison
+## Benchmark Results
 
-| Type | Score | vs Baseline |
-|------|-------|-------------|
-| No memory | 77/100 | — |
-| Hash embeddings | 65/100 | -12 pts ❌ |
-| **Real embeddings** | **74/100** | **-3 pts** |
+| Test | Without Memory | With Mnemo | Improvement |
+|------|----------------|------------|-------------|
+| Novel retrieval | 5% | 85% | +80% |
+| Code retrieval | 60% | 88% | +28% |
+| ROS continuous learning | 25% | 75% | +50% |
 
-**Key finding:** Real embeddings are 9 points better than hash embeddings.
+## API
 
-## 🔧 MCP Server (for Claude)
-
-Add to your Claude config:
-
-```json
-{
-  "mcpServers": {
-    "mnemo": {
-      "command": "uvx",
-      "args": ["mnemo-memory"]
-    }
-  }
-}
-```
+```python
+# Initialize
+mnemo = Mnemo()
 
-### MCP Tools
+# Add memory
+mnemo.add(content, namespace="default", metadata={})
 
-| 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 |
+# Search
+results = mnemo.search(query, top_k=5)
 
-## 📊 Benchmarks vs mem0
+# Get context for LLM injection
+context = mnemo.get_context(query, top_k=3)
 
-| Metric | mem0 | Mnemo |
-|--------|------|-------|
-| 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** |
+# Check if injection would help
+should_inject = mnemo.should_inject(query)
 
-## 🏗️ Architecture
+# Run maintenance (decay + prune)
+mnemo.maintenance_cycle()
 
+# Get statistics
+stats = mnemo.get_stats()
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                         Mnemo                                │
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
-│  │  Semantic   │  │    BM25     │  │   Graph     │         │
-│  │   Search    │  │   Search    │  │   Search    │         │
-│  │  (FAISS)    │  │ (Keywords)  │  │ (NetworkX)  │         │
-│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
-│         │                │                │                 │
-│         └────────────────┴────────────────┘                 │
-│                          │                                  │
-│                   ┌──────┴──────┐                           │
-│                   │   Ranker    │ ← Feedback Learning       │
-│                   └──────┬──────┘                           │
-│                          │                                  │
-│              ┌───────────┴───────────┐                      │
-│              │  Smart Injection      │                      │
-│              │  (Context-Check)      │                      │
-│              └───────────────────────┘                      │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## 📝 API Reference
 
-### Mnemo Class
+## Parameters
 
-```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()
-```
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| similarity_threshold | 0.10 | Min score for search results |
+| quality_threshold | 0.35 | Min quality for new memories |
+| memory_decay_rate | 0.01 | Daily quality decay (1%) |
+| memory_stale_days | 30 | Days before eligible for pruning |
 
-### SearchResult
-
-```python
-@dataclass
-class SearchResult:
-    id: str
-    content: str
-    score: float
-    strategy_scores: Dict[str, float]
-    metadata: Dict
-```
-
-## 🔗 Links
+## 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
+MIT License