cozo-memory 1.2.6 → 1.2.10

package/README.md

@@ -3,8 +3,14 @@
 [![npm](https://img.shields.io/npm/v/cozo-memory)](https://www.npmjs.com/package/cozo-memory)
 [![Node](https://img.shields.io/node/v/cozo-memory)](https://nodejs.org)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![MCP Badge](https://lobehub.com/badge/mcp/tobs-code-cozo-memory)](https://lobehub.com/mcp/tobs-code-cozo-memory)
 
-**Local-first memory for Claude & AI agents with hybrid search, Graph-RAG, and time-travel – all in a single binary, no cloud, no Docker.**
+> **Why Cozo Memory?**  
+> LLMs have short-term memory limits. Standard RAG retrieves documents but can't connect facts across time. Cozo Memory gives your AI agent **persistent, structured memory** – it remembers past conversations, infers relationships, detects contradictions, and explores its knowledge graph – fully on your machine, with **optional local LLM integration via Ollama** for intelligent actions (cleanup, reflection, summarization, agentic routing).
+>
+> Most memory stacks combine separate databases: SQLite for facts, Chroma for vector search, NetworkX for graphs. **CozoDB replaces all of that with one embedded engine**: relational, graph, vector, and full-text search in a single query language, one file, zero sync lag.
+
+**Local-first memory for Claude & AI agents with hybrid search, Graph-RAG, and time-travel – runs entirely on your machine. Optional [Ollama](https://ollama.ai) integration enables LLM-powered actions (cleanup, reflect, summarize, agentic retrieval).**
 
 ## Table of Contents
 
@@ -51,7 +57,7 @@ Now add the server to your MCP client (e.g. Claude Desktop) – see [Integration
 
 ⏳ **Temporal Conflict Resolution** - Automatic detection and resolution of contradictory observations with semantic analysis and audit preservation
 
-🏠 **100% Local** - Embeddings via ONNX/Transformers; no external services, no cloud, complete data ownership
+🏠 **100% Local** - Embeddings via ONNX/Transformers; data stays on your machine. Some advanced features (cleanup, reflect, summarize, agentic search) require an optional [Ollama](https://ollama.ai) service for local LLM inference — but the core search, CRUD, and graph operations work **without any LLM**.
 
 🧠 **Multi-Hop Reasoning** - Logic-aware graph traversal with vector pivots for deep relational reasoning
 
@@ -61,17 +67,36 @@ Now add the server to your MCP client (e.g. Claude Desktop) – see [Integration
 
 ## Positioning & Comparison
 
+### Why CozoDB instead of SQLite + Chroma + NetworkX?
+
+A common first question is: *"Why not just combine existing tools?"*
+
+| If you need... | Typical separate stack | CozoDB Memory |
+| :--- | :--- | :--- |
+| Structured data & relations | **SQLite** / PostgreSQL | ✅ Built-in relational engine |
+| Semantic / vector search | **Chroma** / Qdrant / Pinecone | ✅ HNSW + FTS + RRF in one engine |
+| Graph traversal & reasoning | **NetworkX** / Neo4j | ✅ Native graph queries + PageRank |
+| Time-travel / versioning | Custom audit tables | ✅ Built-in `Validity` time-travel |
+| Unified query language | Multiple APIs + glue code | ✅ Single Datalog query across all dimensions |
+
+**The core insight:** Most memory stacks bolt vector search onto a graph DB, or graph search onto a vector DB. CozoDB is different: it is a **single engine** that natively combines relational, graph, vector, and full-text search. That means:
+
+- **One query language** (Datalog) reaches every dimension.
+- **No sync lag** between separate indexes.
+- **No ETL bridge** between "vector results" and "graph expansion."
+- **Smaller operational surface**: one database file, one process, one dependency chain.
+
+### Comparison with other memory solutions
+
 Most "Memory" MCP servers fall into two categories:
 1. **Simple Knowledge Graphs**: CRUD operations on triples, often only text search
 2. **Pure Vector Stores**: Semantic search (RAG), but little understanding of complex relationships
 
-This server fills the gap in between ("Sweet Spot"): A **local, database-backed memory engine** combining vector, graph, and keyword signals.
-
-### Comparison with other solutions
+This server fills the gap in between ("Sweet Spot"): A **local, database-backed memory engine** combining vector, graph, and keyword signals — powered by CozoDB's unified engine rather than a patchwork of separate databases.
 
 | Feature | **CozoDB Memory (This Project)** | **Official Reference (`@modelcontextprotocol/server-memory`)** | **mcp-memory-service (Community)** | **Database Adapters (Qdrant/Neo4j)** |
 | :--- | :--- | :--- | :--- | :--- |
-| **Backend** | **CozoDB** (Graph + Vector + Relational) | JSON file (`memory.jsonl`) | SQLite / Cloudflare | Specialized DB (only Vector or Graph) |
+| **Backend** | **CozoDB** (Graph + Vector + Relational + FTS in one engine) | JSON file (`memory.jsonl`) | SQLite / Cloudflare | Specialized DB (only Vector or Graph) |
 | **Search Logic** | **Agentic (Auto-Route)**: Hybrid + Graph + Summaries | Keyword only / Exact Graph Match | Vector + Keyword | Mostly only one dimension |
 | **Inference** | **Yes**: Built-in engine for implicit knowledge | No | No ("Dreaming" is consolidation) | No (Retrieval only) |
 | **Community** | **Yes**: Hierarchical Community Summaries | No | No | Only clustering (no summary) |
@@ -89,9 +114,34 @@ The core advantage is **Intelligence and Traceability**: By combining an **Agent
 - **RAM: 1.7 GB minimum** (for default bge-m3 model)
   - Model download: ~600 MB
   - Runtime memory: ~1.1 GB
-  - For lower-spec machines, see [Embedding Model Options](#embedding-model-options) below
+  - ⚡ **Too heavy?** Use `EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2` – only **~400 MB RAM** needed (see [Embedding Model Options](#embedding-model-options))
 - CozoDB native dependency is installed via `cozo-node`
 
+### Optional: Ollama for LLM-powered actions
+
+Some advanced actions use a local LLM via [Ollama](https://ollama.ai) for intelligent
+processing. **The core server works without Ollama** (CRUD, search, graph operations),
+but the following actions require it:
+
+| Action | Purpose |
+|--------|---------|
+| `cleanup` | LLM-backed observation consolidation |
+| `reflect` | Generate insights, detect contradictions |
+| `summarize_communities` | LLM-generated community summaries |
+| `compact` | Session / entity compaction with LLM summarization |
+| `agentic_search` | Query intent classification for auto-routing |
+
+**Setup (if you need these features):**
+```bash
+# 1. Install Ollama from https://ollama.ai
+# 2. Pull a model (e.g. small + fast for dev):
+ollama pull demyagent-4b-i1:Q6_K
+# 3. Ollama runs automatically on http://localhost:11434
+```
+
+If Ollama is not running, the affected actions gracefully fall back to non-LLM behavior
+(where possible) or return a clear error message.
+
 ### Via npm (Easiest)
 
 ```bash
@@ -337,10 +387,10 @@ The interface is reduced to **5 consolidated tools**:
 
 | Tool | Purpose | Key Actions |
 |------|---------|-------------|
-| `mutate_memory` | Write operations | create_entity, update_entity, delete_entity, add_observation, create_relation, transactions, sessions, tasks |
-| `query_memory` | Read operations | search, advancedSearch, context, graph_rag, graph_walking, agentic_search, adaptive_retrieval |
+| `mutate_memory` | Write operations | create_entity, update_entity, delete_entity, add_observation, create_relation, transactions, sessions, tasks, update_observation, batch_delete, manage_tags, batch |
+| `query_memory` | Read operations | search, advancedSearch, context, graph_rag, graph_walking, agentic_search, adaptive_retrieval, list_entities, get_entity_detail, get_session_context, list_sessions |
 | `analyze_graph` | Graph analysis | explore, communities, pagerank, betweenness, hits, shortest_path, semantic_walk |
-| `manage_system` | Maintenance | health, metrics, export, import, cleanup, defrag, reflect, snapshots |
+| `manage_system` | Maintenance | health, metrics, stats, export, import, cleanup, defrag, reflect, snapshots |
 | `edit_user_profile` | User preferences | Edit global user profile with preferences and work style |
 
 > **See [docs/API.md](docs/API.md) for complete API reference with all parameters and examples**
@@ -354,10 +404,12 @@ The interface is reduced to **5 consolidated tools**:
 - This is normal and only happens once
 - Subsequent starts are fast (< 2 seconds)
 
-**Cleanup/Reflect Requires Ollama**
-- If using `cleanup` or `reflect` actions, an Ollama service must be running locally
+**LLM-powered actions require Ollama**
+- The following actions use a local LLM for intelligent processing: `cleanup`, `reflect`, `summarize_communities`, `compact`, `agentic_search`
 - Install Ollama from https://ollama.ai
 - Pull the desired model: `ollama pull demyagent-4b-i1:Q6_K` (or your preferred model)
+- Without Ollama, these actions fall back to non-LLM behavior or return a clear error
+- **Core features (CRUD, search, graph, infer) work without any LLM**
 
 **Windows-Specific**
 - Embeddings are processed on CPU for maximum compatibility
@@ -403,30 +455,6 @@ npm run benchmark    # Runs performance tests
 npm run eval         # Runs evaluation suite
 ```
 
-## Roadmap
-
-### Near-Term (v1.x)
-
-- **GPU Acceleration** - CUDA support for embedding generation (10-50x faster)
-- **Streaming Ingestion** - Real-time data ingestion from logs, APIs, webhooks
-- **Advanced Chunking** - Semantic chunking for `ingest_file` (paragraph-aware splitting)
-- **Query Optimization** - Automatic query plan optimization for complex graph traversals
-- **Additional Export Formats** - Notion, Roam Research, Logseq compatibility
-
-### Mid-Term (v2.x)
-
-- **Multi-Modal Embeddings** - Support for images, audio, code
-- **Distributed Memory** - Sharding and replication for large-scale deployments
-- **Advanced Inference** - Neural-symbolic reasoning, causal inference
-- **Real-Time Sync** - WebSocket-based real-time updates
-- **Web UI** - Browser-based management interface
-
-### Long-Term (v3.x)
-
-- **Federated Learning** - Privacy-preserving collaborative learning
-- **Quantum-Inspired Algorithms** - Advanced graph algorithms
-- **Multi-Agent Coordination** - Shared memory across multiple agents
-
 ## Contributing
 
 Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.