README.md

metadata

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

pip install mnemo-memory

Or with all features:

pip install mnemo-memory[all]  # Includes sentence-transformers, faiss-cpu

🚀 Quick Start

from mnemo import Mnemo

memory = Mnemo()
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:

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}"

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:

{
  "mcpServers": {
    "mnemo": {
      "command": "uvx",
      "args": ["mnemo-memory"]
    }
  }
}

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 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

┌─────────────────────────────────────────────────────────────┐
│                         Mnemo                                │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Semantic   │  │    BM25     │  │   Graph     │         │
│  │   Search    │  │   Search    │  │   Search    │         │
│  │  (FAISS)    │  │ (Keywords)  │  │ (NetworkX)  │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                 │
│         └────────────────┴────────────────┘                 │
│                          │                                  │
│                   ┌──────┴──────┐                           │
│                   │   Ranker    │ ← Feedback Learning       │
│                   └──────┬──────┘                           │
│                          │                                  │
│              ┌───────────┴───────────┐                      │
│              │  Smart Injection      │                      │
│              │  (Context-Check)      │                      │
│              └───────────────────────┘                      │
└─────────────────────────────────────────────────────────────┘

📝 API Reference

Mnemo Class

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

@dataclass
class SearchResult:
    id: str
    content: str
    score: float
    strategy_scores: Dict[str, float]
    metadata: Dict

🔗 Links

• Demo Space
• MCP Server
• GitHub Issues

📄 License

MIT License - Use freely in your projects!

---

Built with ❤️ for the AI community