cozo-memory 1.0.9 → 1.1.1

package/README.md

@@ -63,6 +63,10 @@ Now you can add the server to your MCP client (e.g. Claude Desktop).
 
 🧠 **Agentic Retrieval Layer (v2.0)** - Auto-routing engine that analyzes query intent via local LLM to select the optimal search strategy (Vector, Graph, or Community)
 
+🧠 **Multi-Level Memory (v2.0)** - Context-aware memory system with built-in session and task management
+
+🎯 **Tiny Learned Reranker (v2.0)** - Integrated Cross-Encoder model (`ms-marco-MiniLM-L-6-v2`) for ultra-precise re-ranking of top search results
+
 🎯 **Multi-Vector Support (since v1.7)** - Dual embeddings per entity: content-embedding for context, name-embedding for identification
 
 ⚡ **Semantic Caching (since v0.8.5)** - Two-level cache (L1 memory + L2 persistent) with semantic query matching
@@ -75,7 +79,7 @@ Now you can add the server to your MCP client (e.g. Claude Desktop).
 
 🏗️ **Hierarchical GraphRAG (v2.0)** - Automatic generation of thematic "Community Summaries" using local LLMs to enable global "Big Picture" reasoning
 
-🧹 **Janitor Service** - LLM-backed automatic cleanup with hierarchical summarization and observation pruning
+🧹 **Janitor Service** - LLM-backed automatic cleanup with hierarchical summarization, observation pruning, and **automated session compression**
 
 👤 **User Preference Profiling** - Persistent user preferences with automatic 50% search boost
 
@@ -191,8 +195,10 @@ This tool compares strategies using a synthetic dataset and measures **Recall@K*
 | Method | Recall@10 | Avg Latency | Best For |
 | :--- | :--- | :--- | :--- |
 | **Graph-RAG** | **1.00** | **~32 ms** | Deep relational reasoning |
+| **Graph-RAG (Reranked)** | **1.00** | **~36 ms** | Maximum precision for relational data |
 | **Graph-Walking** | 1.00 | ~50 ms | Associative path exploration |
 | **Hybrid Search** | 1.00 | ~89 ms | Broad factual retrieval |
+| **Reranked Search** | 1.00 | ~20 ms* | Ultra-precise factual search (Warm cache) |
 
 ## Architecture
 
@@ -364,6 +370,7 @@ CozoDB Memory includes a full-featured CLI for all operations:
 # System operations
 cozo-memory system health
 cozo-memory system metrics
+cozo-memory system reflect
 
 # Entity operations
 cozo-memory entity create -n "MyEntity" -t "person" -m '{"age": 30}'
@@ -379,11 +386,19 @@ cozo-memory relation create --from <id1> --to <id2> --type "knows" -s 0.8
 # Search
 cozo-memory search query -q "search term" -l 10
 cozo-memory search context -q "context query"
+cozo-memory search agentic -q "agentic query"
 
 # Graph operations
 cozo-memory graph explore -s <entity-id> -h 3
 cozo-memory graph pagerank
 cozo-memory graph communities
+cozo-memory graph summarize
+
+# Session & Task management
+cozo-memory session start -n "My Session"
+cozo-memory session stop -i <session-id>
+cozo-memory task start -n "My Task" -s <session-id>
+cozo-memory task stop -i <task-id>
 
 # Export/Import
 cozo-memory export json -o backup.json --include-metadata --include-relationships --include-observations
@@ -508,8 +523,8 @@ The interface is reduced to **4 consolidated tools**. The concrete operation is
 
 | Tool | Purpose | Key Actions |
 |------|---------|-------------|
-| `mutate_memory` | Write operations | create_entity, update_entity, delete_entity, add_observation, create_relation, run_transaction, add_inference_rule, ingest_file |
-| `query_memory` | Read operations | search, advancedSearch, context, entity_details, history, graph_rag, graph_walking, agentic_search |
+| `mutate_memory` | Write operations | create_entity, update_entity, delete_entity, add_observation, create_relation, start_session, stop_session, start_task, stop_task, run_transaction, add_inference_rule, ingest_file |
+| `query_memory` | Read operations | search, advancedSearch, context, entity_details, history, graph_rag, graph_walking, agentic_search (Multi-Level Context support) |
 | `analyze_graph` | Graph analysis | explore, communities, pagerank, betweenness, hits, shortest_path, bridge_discovery, semantic_walk, infer_relations |
 | `manage_system` | Maintenance | health, metrics, export_memory, import_memory, snapshot_create, snapshot_list, snapshot_diff, cleanup, reflect, summarize_communities, clear_memory |
 
@@ -521,6 +536,10 @@ Actions:
 - `delete_entity`: `{ entity_id }`
 - `add_observation`: `{ entity_id?, entity_name?, entity_type?, text, metadata? }`
 - `create_relation`: `{ from_id, to_id, relation_type, strength?, metadata? }`
+- `start_session`: `{ name?, metadata? }` **(New v2.0)**: Starts a new session context (metadata can include `user_id`, `project`, etc.)
+- `stop_session`: `{ session_id }` **(New v2.0)**: Closes/archives an active session.
+- `start_task`: `{ name, session_id?, metadata? }` **(New v2.0)**: Starts a specific task within a session.
+- `stop_task`: `{ task_id }` **(New v2.0)**: Marks a task as completed.
 - `run_transaction`: `{ operations: Array<{ action, params }> }` **(New v1.2)**: Executes multiple operations atomically.
 - `add_inference_rule`: `{ name, datalog }`
 - `ingest_file`: `{ format, file_path?, content?, entity_id?, entity_name?, entity_type?, chunking?, metadata?, observation_metadata?, deduplicate?, max_observations? }`
@@ -608,14 +627,14 @@ PDF Ingestion via File Path:
 ### query_memory (Read)
 
 Actions:
-- `search`: `{ query, limit?, entity_types?, include_entities?, include_observations? }`
-- `advancedSearch`: `{ query, limit?, filters?, graphConstraints?, vectorOptions? }` **(New v1.1 / v1.4)**: Extended search with native HNSW filters (types) and robust post-filtering (metadata, time).
+- `search`: `{ query, limit?, entity_types?, include_entities?, include_observations?, rerank? }`
+- `advancedSearch`: `{ query, limit?, filters?, graphConstraints?, vectorOptions?, rerank? }`
 - `context`: `{ query, context_window?, time_range_hours? }`
 - `entity_details`: `{ entity_id, as_of? }`
 - `history`: `{ entity_id }`
-- `graph_rag`: `{ query, max_depth?, limit?, filters? }` Graph-based reasoning. Finds vector seeds (with inline filtering) first and then expands transitive relationships. Uses recursive Datalog for efficient BFS expansion.
+- `graph_rag`: `{ query, max_depth?, limit?, filters?, rerank? }` Graph-based reasoning. Finds vector seeds (with inline filtering) first and then expands transitive relationships. Uses recursive Datalog for efficient BFS expansion.
 - `graph_walking`: `{ query, start_entity_id?, max_depth?, limit? }` (v1.7) Recursive semantic graph search. Starts at vector seeds or a specific entity and follows relationships to other semantically relevant entities. Ideal for deeper path exploration.
-- `agentic_search`: `{ query, limit? }` **(New v2.0)**: **Auto-Routing Search**. Uses a local LLM (Ollama) to analyze query intent and automatically routes it to the most appropriate strategy (`vector_search`, `graph_walk`, or `community_summary`).
+- `agentic_search`: `{ query, limit?, rerank? }` **(New v2.0)**: **Auto-Routing Search**. Uses a local LLM (Ollama) to analyze query intent and automatically routes it to the most appropriate strategy (`vector_search`, `graph_walk`, or `community_summary`).
 - `get_relation_evolution`: `{ from_id, to_id?, since?, until? }` (in `analyze_graph`) Shows temporal development of relationships including time range filter and diff summary.
 
 Important Details:
@@ -717,6 +736,7 @@ Janitor Cleanup Details:
 - `cleanup` supports `dry_run`: with `confirm: false` only candidates are listed.
 - With `confirm: true`, the Janitor becomes active:
   - **Hierarchical Summarization**: Detects isolated or old observations, has them summarized by a local LLM (Ollama), and creates a new `ExecutiveSummary` node. Old fragments are deleted to reduce noise while preserving knowledge.
+  - **Automated Session Compression**: Automatically identifies inactive sessions, summarizes their activity into a few bullet points, and stores the summary in the User Profile while marking the session as archived.
 
 **Before Janitor:**
 ```
@@ -885,6 +905,15 @@ Uncertainty/Transparency:
 - Inference candidates are marked as `source: "inference"` and provide a short reason (uncertainty hint) in the result.
 - In `context` output, inferred entities additionally carry an `uncertainty_hint` so an LLM can distinguish "hard fact" vs. "conjecture".
 
+### Tiny Learned Reranker (Cross-Encoder)
+
+For maximum precision, CozoDB Memory integrates a specialized **Cross-Encoder Reranker** (Phase 2 RAG).
+
+- **Model**: `Xenova/ms-marco-MiniLM-L-6-v2` (Local ONNX)
+- **Mechanism**: After initial hybrid retrieval, the top candidates (up to 30) are re-evaluated by the cross-encoder. Unlike bi-encoders (vectors), cross-encoders process query and document simultaneously, capturing deep semantic nuances.
+- **Latency**: Minimal overhead (~4-6ms for top 10 candidates).
+- **Supported Tools**: Available as a `rerank: true` parameter in `search`, `advancedSearch`, `graph_rag`, and `agentic_search`.
+
 ### Inference Engine
 
 Inference uses multiple strategies (non-persisting):

package/dist/cli-commands.js

@@ -110,6 +110,12 @@ class CLICommands {
     async advancedSearch(params) {
         return await this.server.advancedSearch(params);
     }
+    async agenticSearch(query, limit) {
+        return await this.server.hybridSearch.agenticRetrieve({
+            query,
+            limit: limit || 10
+        });
+    }
     async context(query, contextWindow, timeRangeHours) {
         // Use advancedSearch with appropriate parameters
         return await this.server.advancedSearch({
@@ -146,6 +152,12 @@ class CLICommands {
     async communities() {
         return await this.server.recomputeCommunities();
     }
+    async summarizeCommunities(model, minCommunitySize) {
+        return await this.server.summarizeCommunities({
+            model,
+            min_community_size: minCommunitySize
+        });
+    }
     // System operations
     async health() {
         const entityCount = await this.server.db.run('?[count(id)] := *entity{id, @ "NOW"}');
@@ -162,6 +174,13 @@ class CLICommands {
         // Access private metrics via type assertion
         return this.server.metrics;
     }
+    async reflect(entityId, model, mode) {
+        return await this.server.reflectMemory({
+            entity_id: entityId,
+            model,
+            mode
+        });
+    }
     async exportMemory(format, options) {
         const { ExportImportService } = await import('./export-import-service.js');
         // Create a simple wrapper that implements DbService interface
@@ -206,5 +225,18 @@ class CLICommands {
     async getUserProfile() {
         return await this.server.editUserProfile({});
     }
+    // Session and Task management
+    async startSession(name, metadata) {
+        return await this.server.startSession({ name, metadata });
+    }
+    async stopSession(id) {
+        return await this.server.stopSession({ id });
+    }
+    async startTask(name, sessionId, metadata) {
+        return await this.server.startTask({ name, session_id: sessionId, metadata });
+    }
+    async stopTask(id) {
+        return await this.server.stopTask({ id });
+    }
 }
 exports.CLICommands = CLICommands;

package/dist/cli.js

@@ -203,6 +203,23 @@ search
         handleError(error);
     }
 });
+search
+    .command('agentic')
+    .description('Perform agentic retrieval with automatic routing')
+    .requiredOption('-q, --query <query>', 'Search query')
+    .option('-l, --limit <number>', 'Result limit', parseInt, 10)
+    .option('-f, --format <format>', 'Output format (json|pretty)', 'pretty')
+    .action(async (options) => {
+    try {
+        await cli.init();
+        const result = await cli.agenticSearch(options.query, options.limit);
+        formatOutput(result, options.format);
+        await cli.close();
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
 // Graph commands
 const graph = program.command('graph').description('Graph operations');
 graph
@@ -255,6 +272,23 @@ graph
         handleError(error);
     }
 });
+graph
+    .command('summarize')
+    .description('Generate hierarchical community summaries (GraphRAG)')
+    .option('-m, --model <model>', 'LLM model to use for summaries')
+    .option('--min-size <number>', 'Minimum community size', parseInt)
+    .option('-f, --format <format>', 'Output format (json|pretty)', 'pretty')
+    .action(async (options) => {
+    try {
+        await cli.init();
+        const result = await cli.summarizeCommunities(options.model, options.minSize);
+        formatOutput(result, options.format);
+        await cli.close();
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
 // System commands
 const system = program.command('system').alias('sys').description('System operations');
 system
@@ -287,6 +321,24 @@ system
         handleError(error);
     }
 });
+system
+    .command('reflect')
+    .description('Perform self-reflection to discover implicit relations')
+    .option('-i, --id <id>', 'Entity ID to reflect on (optional)')
+    .option('-m, --model <model>', 'LLM model to use')
+    .option('--mode <mode>', 'Reflection mode (summary|discovery)', 'discovery')
+    .option('-f, --format <format>', 'Output format (json|pretty)', 'pretty')
+    .action(async (options) => {
+    try {
+        await cli.init();
+        const result = await cli.reflect(options.id, options.model, options.mode);
+        formatOutput(result, options.format);
+        await cli.close();
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
 // Export/Import commands
 const exportCmd = program.command('export').description('Export memory');
 exportCmd
@@ -487,4 +539,77 @@ profile
         handleError(error);
     }
 });
+// Session commands
+const session = program.command('session').description('Session management');
+session
+    .command('start')
+    .description('Start a new session')
+    .option('-n, --name <name>', 'Session name')
+    .option('-m, --metadata <json>', 'Metadata as JSON string')
+    .option('-f, --format <format>', 'Output format (json|pretty)', 'pretty')
+    .action(async (options) => {
+    try {
+        await cli.init();
+        const metadata = options.metadata ? JSON.parse(options.metadata) : undefined;
+        const result = await cli.startSession(options.name, metadata);
+        formatOutput(result, options.format);
+        await cli.close();
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
+session
+    .command('stop')
+    .description('Stop a session')
+    .requiredOption('-i, --id <id>', 'Session ID')
+    .option('-f, --format <format>', 'Output format (json|pretty)', 'pretty')
+    .action(async (options) => {
+    try {
+        await cli.init();
+        const result = await cli.stopSession(options.id);
+        formatOutput(result, options.format);
+        await cli.close();
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
+// Task commands
+const task = program.command('task').description('Task management');
+task
+    .command('start')
+    .description('Start a new task')
+    .requiredOption('-n, --name <name>', 'Task name')
+    .option('-s, --session-id <id>', 'Session ID')
+    .option('-m, --metadata <json>', 'Metadata as JSON string')
+    .option('-f, --format <format>', 'Output format (json|pretty)', 'pretty')
+    .action(async (options) => {
+    try {
+        await cli.init();
+        const metadata = options.metadata ? JSON.parse(options.metadata) : undefined;
+        const result = await cli.startTask(options.name, options.sessionId, metadata);
+        formatOutput(result, options.format);
+        await cli.close();
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
+task
+    .command('stop')
+    .description('Stop a task')
+    .requiredOption('-i, --id <id>', 'Task ID')
+    .option('-f, --format <format>', 'Output format (json|pretty)', 'pretty')
+    .action(async (options) => {
+    try {
+        await cli.init();
+        const result = await cli.stopTask(options.id);
+        formatOutput(result, options.format);
+        await cli.close();
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
 program.parse();