Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,19 @@
+---
+license: mit
+library_name: mnemo
+tags:
+  - memory
+  - retrieval
+  - rag
+  - semantic-search
+  - knowledge-graph
+  - faiss
+  - bm25
+language:
+  - en
+pipeline_tag: feature-extraction
+---
+
 # Mnemo: Semantic-Loop Memory
 
 > *Named after Mnemosyne, Greek goddess of memory*
@@ -7,6 +23,10 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 
+## 🎮 Try the Demo
+
+👉 [**Live Demo on HuggingFace Spaces**](https://huggingface.co/spaces/AthelaPerk/mnemo)
+
 ---
 
 ## 🏆 Benchmarks vs mem0
@@ -38,6 +58,12 @@
 
 ## 🚀 Quick Start
 
+```bash
+git clone https://huggingface.co/AthelaPerk/mnemo-memory
+cd mnemo-memory
+pip install -r requirements.txt
+```
+
 ```python
 from mnemo import Mnemo
 
@@ -51,40 +77,29 @@ m.add("Team meeting every Tuesday at 2pm")
 
 # Search (0.27ms average!)
 results = m.search("notification preferences")
-print(results)
+print(results[0].content)  # "User prefers dark mode..."
 
-# With feedback learning
-m.feedback("notification preferences", "mem_001", relevance=0.9)
-# Future searches now boosted based on feedback
+# Feedback learning
+m.feedback("notification preferences", results[0].id, relevance=0.9)
 ```
 
 ---
 
 ## 🧠 Architecture
 
-Mnemo uses a **Semantic-Loop Memory** architecture:
-
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                         MNEMO                                │
 ├─────────────────────────────────────────────────────────────┤
-│                                                              │
 │  Query → [Intent Detection] → [Multi-Strategy Retrieval]    │
-│              │                        │                      │
-│              ▼                        ▼                      │
-│     ┌──────────────┐    ┌─────────────────────────┐         │
-│     │    Parse     │    │  Semantic  │  BM25  │  Graph │    │
-│     │   Intent     │    │   (50%)   │ (30%) │ (20%)  │     │
-│     └──────────────┘    └─────────────────────────┘         │
-│              │                        │                      │
-│              ▼                        ▼                      │
-│     ┌──────────────┐         ┌──────────────┐               │
-│     │  Knowledge   │◄───────►│   Feedback   │               │
-│     │    Graph     │         │    Loop      │               │
-│     └──────────────┘         └──────────────┘               │
-│                                      │                       │
-│                              [Learns & Improves]             │
-│                                                              │
+│                                       │                      │
+│                         ┌─────────────┴─────────────┐       │
+│                         │ Semantic │ BM25 │ Graph   │       │
+│                         │   50%    │ 30%  │  20%    │       │
+│                         └─────────────┬─────────────┘       │
+│                                       │                      │
+│                              [Feedback Loop]                 │
+│                           (Learns & Improves)                │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -99,85 +114,43 @@ Mnemo uses a **Semantic-Loop Memory** architecture:
 
 ---
 
-## 🔧 Installation
-
-```bash
-pip install mnemo-memory
-```
-
-Or from source:
-```bash
-git clone https://github.com/yourusername/mnemo
-cd mnemo
-pip install -e .
-```
-
-### Dependencies
-```
-faiss-cpu
-networkx
-rank_bm25
-numpy
-```
-
----
-
-## 📖 Advanced Usage
+## 📖 API Reference
 
-### Query with Intent Detection
+### Basic Usage
 
 ```python
 from mnemo import Mnemo
 
-m = Mnemo()
-m.add("Cardiovascular disease affects the heart and blood vessels")
-
-result = m.search("What is heart disease?")
-print(result['intent'])  # 'factual'
-print(result['results'])  # Retrieved memories
-```
-
-### Feedback Learning
-
-```python
-# Record what was helpful
-m.feedback(
-    query="heart disease",
-    memory_id="med_001", 
-    relevance=0.9  # Very relevant
+m = Mnemo(
+    embedding_dim=384,      # BGE-small compatible
+    semantic_weight=0.5,    # Weight for semantic search
+    bm25_weight=0.3,        # Weight for keyword search
+    graph_weight=0.2        # Weight for graph traversal
 )
 
-m.feedback(
-    query="heart disease",
-    memory_id="tech_001",
-    relevance=-0.5  # Not relevant
-)
+# Add memory
+mem_id = m.add("content", metadata={"key": "value"})
 
-# Future searches automatically adjusted
-```
+# Search
+results = m.search("query", top_k=5)
+for r in results:
+    print(r.id, r.score, r.content)
 
-### Knowledge Graph
+# Feedback
+m.feedback("query", mem_id, relevance=0.9)  # -1 to 1
 
-```python
-# Entities are automatically extracted and linked
-m.add("Dr. Smith at Mayo Clinic studies cardiac diseases")
-
-# Query relationships
-graph = m.get_knowledge_graph()
-neighbors = graph.get_neighbors("Dr. Smith")
+# Stats
+print(m.get_stats())
 ```
 
-### System Stats
+### SearchResult Object
 
 ```python
-stats = m.get_stats()
-print(stats)
-# {
-#   'vector_store': {'size': 100, 'searches': 50},
-#   'knowledge_graph': {'entities': 45, 'relations': 23},
-#   'cache': {'hit_rate': '34.5%'},
-#   'retrieval': {'strategy_wins': {'semantic': 30, 'keyword': 15, 'graph': 5}}
-# }
+result.id              # Memory ID
+result.content         # Memory content
+result.score           # Combined score
+result.strategy_scores # {'semantic': 0.5, 'bm25': 0.3, 'graph': 0.1}
+result.metadata        # Original metadata
 ```
 
 ---
@@ -191,7 +164,7 @@ Mnemo was designed with **EU AI Act Article 10** compliance in mind:
 - ✅ **No external API calls** - Data never leaves your infrastructure
 - ✅ **Traceable reasoning** - Understand why results were returned
 
-*From the team behind [NRA-19](https://github.com/yourusername/nra-19), the medical AI bias detection benchmark.*
+*From the team behind NRA-19 medical AI benchmark.*
 
 ---
 
@@ -208,38 +181,11 @@ Mnemo was designed with **EU AI Act Article 10** compliance in mind:
 
 ---
 
-## 📊 Detailed Benchmarks
-
-Tested on 5 documents, 15 queries:
-
-### Latency
-```
-Ingestion:
-  mem0:  31.1ms avg per document
-  Mnemo:  0.8ms avg per document
-  Winner: Mnemo (39x faster)
-
-Search:
-  mem0:  5.73ms avg (p50: 5.17ms, p99: 8.21ms)
-  Mnemo: 0.27ms avg (p50: 0.25ms, p99: 0.36ms)  
-  Winner: Mnemo (21x faster)
-```
-
-### Retrieval Strategy Distribution
-```
-Mnemo retrieval wins by strategy:
-  Semantic: 50 (77%)
-  Keyword:  15 (23%)
-  Graph:     0 (0%)
-```
-
----
-
 ## 🗺️ Roadmap
 
-- [ ] Sentence-transformers integration for real embeddings
-- [ ] Persistent storage backends (SQLite, PostgreSQL)
-- [ ] Multi-user / tenant support
+- [ ] Sentence-transformers integration
+- [ ] Persistent storage (SQLite, PostgreSQL)
+- [ ] Multi-user support
 - [ ] REST API server
 - [ ] LangChain integration
 - [ ] LlamaIndex integration
@@ -247,31 +193,14 @@ Mnemo retrieval wins by strategy:
 
 ---
 
-## 🤝 Contributing
-
-Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
-
----
-
 ## 📜 License
 
-MIT License - see [LICENSE](LICENSE).
+MIT License
 
 ---
 
-## 🙏 Acknowledgments
+## 🙏 Etymology
 
-- Named after **Mnemosyne** (Μνημοσύνη), Greek goddess of memory and mother of the Muses
-- Architecture inspired by research in cognitive memory systems
-- Built for the open-source AI community
-
----
-
-## 📬 Contact
-
-- GitHub Issues for bugs/features
-- Discussions for questions
-
----
+Named after **Mnemosyne** (Μνημοσύνη), the Greek goddess of memory and mother of the nine Muses. In Greek mythology, she was one of the Titans and personified memory itself.
 
 *Mnemo: Memory that learns.*