cozo-memory 1.1.0 → 1.1.2

package/README.md

@@ -63,6 +63,8 @@ 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
@@ -77,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
 
@@ -219,10 +221,10 @@ graph TB
     Services --> Inference
     Services --> DB
     
-    style Client fill:#e1f5ff
-    style Server fill:#fff4e1
-    style Services fill:#f0e1ff
-    style DB fill:#e1ffe1
+    style Client fill:#e1f5ff,color:#000
+    style Server fill:#fff4e1,color:#000
+    style Services fill:#f0e1ff,color:#000
+    style DB fill:#e1ffe1,color:#000
 ```
 
 ### Graph-Walking Visualization
@@ -243,12 +245,12 @@ graph LR
     E1 -->|colleague_of| E4
     E4 -.semantic: also relevant.-> E2
     
-    style Start fill:#e1f5ff
-    style V1 fill:#fff4e1
-    style E1 fill:#ffe1e1
-    style E2 fill:#e1ffe1
-    style E3 fill:#f0e1ff
-    style E4 fill:#ffe1e1
+    style Start fill:#e1f5ff,color:#000
+    style V1 fill:#fff4e1,color:#000
+    style E1 fill:#ffe1e1,color:#000
+    style E2 fill:#e1ffe1,color:#000
+    style E3 fill:#f0e1ff,color:#000
+    style E4 fill:#ffe1e1,color:#000
 ```
 
 ## Installation
@@ -368,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}'
@@ -383,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
@@ -512,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 |
 
@@ -525,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? }`
@@ -721,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:**
 ```

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();

package/dist/hybrid-search.js

@@ -78,6 +78,35 @@ class HybridSearch {
             return { ...r, score };
         });
     }
+    applyContextBoost(results, options) {
+        const { session_id, task_id } = options;
+        if (!session_id && !task_id)
+            return results;
+        return results.map(result => {
+            let boost = 1.0;
+            let reasons = [];
+            const metadata = result.metadata || {};
+            if (task_id && metadata.task_id === task_id) {
+                boost += 0.5;
+                reasons.push("Task Match");
+            }
+            if (session_id && metadata.session_id === session_id) {
+                boost += 0.3;
+                reasons.push("Session Match");
+            }
+            if (boost > 1.0) {
+                // Cap the score at 1.0 to stay within standard search score range
+                const newScore = Math.min(1.0, result.score * boost);
+                return {
+                    ...result,
+                    score: newScore,
+                    explanation: (typeof result.explanation === 'string' ? result.explanation : JSON.stringify(result.explanation)) +
+                        ` | Context Boost (x${boost.toFixed(1)}): ${reasons.join(', ')}`
+                };
+            }
+            return result;
+        });
+    }
     async applyReranking(query, results) {
         if (results.length <= 1)
             return results;
@@ -214,10 +243,6 @@ class HybridSearch {
             `:sort -score`,
             `:limit $limit`
         ].join('\n').trim();
-        console.error('--- DEBUG: Cozo Datalog Query ---');
-        console.error(datalogQuery);
-        console.error('--- DEBUG: Params ---');
-        console.error(JSON.stringify(params, null, 2));
         try {
             const results = await this.db.run(datalogQuery, params);
             let searchResults = results.rows.map((r) => ({
@@ -244,7 +269,8 @@ class HybridSearch {
                     return Object.entries(filters.metadata).every(([key, val]) => r.metadata[key] === val);
                 });
             }
-            const finalResults = this.applyTimeDecay(searchResults);
+            const timeDecayedResults = this.applyTimeDecay(searchResults);
+            const finalResults = this.applyContextBoost(timeDecayedResults, options);
             // Phase 3: Reranking
             if (options.rerank) {
                 const rerankedResults = await this.applyReranking(options.query, finalResults);
@@ -339,7 +365,6 @@ class HybridSearch {
       :sort -score
       :limit $limit
     `.trim();
-        console.error("[HybridSearch] Graph-RAG Datalog Query:\n", datalogQuery);
         try {
             const results = await this.db.run(datalogQuery, params);
             let searchResults = results.rows.map((r) => ({

package/dist/index.js

@@ -88,6 +88,8 @@ class MemoryServer {
     }
     async janitorCleanup(args) {
         await this.initPromise;
+        console.error(`[Janitor] Starting cleanup (auto-compressing sessions first)...`);
+        await this.compressSessions({ model: args.model });
         const olderThanDays = Math.max(1, Math.floor(args.older_than_days ?? 30));
         const maxObservations = Math.max(1, Math.floor(args.max_observations ?? 20));
         const minEntityDegree = Math.max(0, Math.floor(args.min_entity_degree ?? 2));
@@ -333,6 +335,69 @@ class MemoryServer {
             results,
         };
     }
+    async compressSessions(args) {
+        const model = args.model ?? "demyagent-4b-i1:Q6_K";
+        const inactiveThreshold = Date.now() - 30 * 60 * 1000; // 30 minutes
+        try {
+            // 1. Find inactive open sessions
+            const inactiveRes = await this.db.run(`?[session_id, last_active, metadata] := *session_state{session_id, last_active, status, metadata}, status == 'open', last_active < $threshold`, { threshold: inactiveThreshold });
+            if (inactiveRes.rows.length === 0) {
+                console.error(`[Janitor] No inactive sessions found for compression.`);
+                return;
+            }
+            console.error(`[Janitor] Found ${inactiveRes.rows.length} inactive sessions to compress.`);
+            for (const row of inactiveRes.rows) {
+                const sessionId = row[0];
+                const lastActive = row[1];
+                const metadata = row[2];
+                // 2. Fetch observations for this session
+                const obsRes = await this.db.run(`?[text] := *observation{session_id: $session_id, text, @ "NOW"}`, { session_id: sessionId });
+                if (obsRes.rows.length > 0) {
+                    const sessionLogs = obsRes.rows.map((r) => r[0]);
+                    // 3. Summarize using LLM
+                    const systemPrompt = "You are a memory consolidation service. Summarize the following session logs into exactly 2-3 concise bullet points for long-term storage. Respond ONLY with the bullet points.";
+                    const userPrompt = `Session Logs for ${sessionId}:\n\n` + sessionLogs.join('\n');
+                    let summaryText;
+                    try {
+                        const ollamaMod = await import("ollama");
+                        const ollamaClient = ollamaMod?.default ?? ollamaMod;
+                        const response = await ollamaClient.chat({
+                            model,
+                            messages: [
+                                { role: "system", content: systemPrompt },
+                                { role: "user", content: userPrompt },
+                            ],
+                        });
+                        summaryText = response?.message?.content?.trim?.() ?? "";
+                    }
+                    catch (e) {
+                        console.warn(`[Janitor] LLM failed for session ${sessionId}: ${e.message}. Using basic concatenation.`);
+                        summaryText = sessionLogs.join('\n').slice(0, 500);
+                    }
+                    if (summaryText) {
+                        // 4. Write compression summary to global user profile
+                        await this.addObservation({
+                            entity_id: "global_user_profile",
+                            text: `Session Summary (${sessionId}):\n${summaryText}`,
+                            metadata: {
+                                kind: "session_compression",
+                                original_session_id: sessionId,
+                                summarized_at: new Date().toISOString()
+                            }
+                        });
+                    }
+                }
+                // 5. Mark session as compressed
+                await this.db.run(`?[session_id, last_active, status, metadata] <- $data
+           :put session_state {session_id, last_active, status, metadata}`, {
+                    data: [[sessionId, lastActive, "compressed", metadata]]
+                });
+            }
+        }
+        catch (e) {
+            console.error(`[Janitor] Session compression error:`, e.message);
+        }
+    }
     async advancedSearch(args) {
         await this.initPromise;
         return this.hybridSearch.advancedSearch(args);
@@ -699,7 +764,7 @@ class MemoryServer {
             // Observation Table
             if (!relations.includes("observation")) {
                 try {
-                    await this.db.run(`{:create observation {id: String, created_at: Validity => entity_id: String, text: String, embedding: <F32; ${EMBEDDING_DIM}>, metadata: Json}}`);
+                    await this.db.run(`{:create observation {id: String, created_at: Validity => entity_id: String, session_id: String, task_id: String, text: String, embedding: <F32; ${EMBEDDING_DIM}>, metadata: Json}}`);
                     console.error("[Schema] Observation table created.");
                 }
                 catch (e) {
@@ -707,8 +772,11 @@ class MemoryServer {
                 }
             }
             else {
+                const columnsRes = await this.db.run(`::columns observation`);
+                const columns = columnsRes.rows.map((r) => r[0]);
                 const timeTravelReady = await this.isTimeTravelReady("observation");
-                if (!timeTravelReady) {
+                if (!columns.includes("session_id") || !columns.includes("task_id") || !timeTravelReady) {
+                    console.error("[Schema] Migrating observation table for Session/Task support...");
                     // Drop indices before migration
                     try {
                         await this.db.run("::hnsw drop observation:semantic");
@@ -722,13 +790,26 @@ class MemoryServer {
                         await this.db.run("::lsh drop observation:lsh");
                     }
                     catch (e) { }
-                    await this.db.run(`
-            ?[id, created_at, entity_id, text, embedding, metadata] :=
-              *observation{id, entity_id, text, embedding, metadata, created_at: created_at_raw},
-              created_at = [created_at_raw, true]
-            :replace observation {id: String, created_at: Validity => entity_id: String, text: String, embedding: <F32; ${EMBEDDING_DIM}>, metadata: Json}
-          `);
-                    console.error("[Schema] Observation table migrated (Validity).");
+                    if (!timeTravelReady) {
+                        await this.db.run(`
+              ?[id, created_at, entity_id, session_id, task_id, text, embedding, metadata] :=
+                *observation{id, entity_id, text, embedding, metadata, created_at: created_at_raw},
+                created_at = [created_at_raw, true],
+                session_id = "",
+                task_id = ""
+              :replace observation {id: String, created_at: Validity => entity_id: String, session_id: String, task_id: String, text: String, embedding: <F32; ${EMBEDDING_DIM}>, metadata: Json}
+            `);
+                    }
+                    else {
+                        await this.db.run(`
+              ?[id, created_at, entity_id, session_id, task_id, text, embedding, metadata] :=
+                *observation{id, entity_id, text, embedding, metadata, created_at},
+                session_id = "",
+                task_id = ""
+              :replace observation {id: String, created_at: Validity => entity_id: String, session_id: String, task_id: String, text: String, embedding: <F32; ${EMBEDDING_DIM}>, metadata: Json}
+            `);
+                    }
+                    console.error("[Schema] Observation table migrated (Session/Task/Validity).");
                 }
             }
             try {
@@ -867,6 +948,26 @@ class MemoryServer {
                     console.error("[Schema] Snapshot table error:", e.message);
                 }
             }
+            // Session State Table
+            if (!relations.includes("session_state")) {
+                try {
+                    await this.db.run('{:create session_state {session_id: String => last_active: Int, status: String, metadata: Json}}');
+                    console.error("[Schema] Session State table created.");
+                }
+                catch (e) {
+                    console.error("[Schema] Session State table error:", e.message);
+                }
+            }
+            // Task State Table
+            if (!relations.includes("task_state")) {
+                try {
+                    await this.db.run('{:create task_state {task_id: String => status: String, session_id: String, metadata: Json}}');
+                    console.error("[Schema] Task State table created.");
+                }
+                catch (e) {
+                    console.error("[Schema] Task State table error:", e.message);
+                }
+            }
             if (!relations.includes("inference_rule")) {
                 try {
                     await this.db.run('{:create inference_rule {id: String => name: String, datalog: String, created_at: Int}}');
@@ -1302,11 +1403,37 @@ class MemoryServer {
                 }
             }
             const now = Date.now() * 1000;
+            const session_id = args.session_id ?? "";
+            const task_id = args.task_id ?? "";
             await this.db.run(`
-        ?[id, created_at, entity_id, text, embedding, metadata] <- [
-          [$id, [${now}, true], $entity_id, $text, $embedding, $metadata]
-        ] :insert observation {id, created_at => entity_id, text, embedding, metadata}
-      `, { id, entity_id: entityId, text: args.text, embedding, metadata: args.metadata || {} });
+        ?[id, created_at, entity_id, session_id, task_id, text, embedding, metadata] <- [
+          [$id, [${now}, true], $entity_id, $session, $task, $text, $embedding, $metadata]
+        ] :insert observation {id, created_at => entity_id, session_id, task_id, text, embedding, metadata}
+      `, {
+                id,
+                entity_id: entityId,
+                session: session_id,
+                task: task_id,
+                text: args.text,
+                embedding,
+                metadata: args.metadata || {}
+            });
+            // Update session activity if session_id is provided
+            if (session_id) {
+                try {
+                    await this.db.run(`
+            ?[id, last_active, status, metadata] :=
+              *session_state{id, metadata},
+              id = $id,
+              last_active = $now,
+              status = "active"
+            :update session_state {id => last_active, status, metadata}
+          `, { id: session_id, now: Math.floor(now / 1000000) });
+                }
+                catch (e) {
+                    console.warn(`[AddObservation] Session activity update failed for ${session_id}:`, e.message);
+                }
+            }
             // Optional: Automatic inference after new observation (in background)
             const suggestionsRaw = await this.inferenceEngine.inferRelations(entityId);
             const suggestions = await this.formatInferredRelationsForContext(suggestionsRaw);
@@ -1314,6 +1441,8 @@ class MemoryServer {
             return {
                 id,
                 entity_id: entityId,
+                session_id,
+                task_id,
                 created_at: now,
                 created_at_iso,
                 status: "Observation saved",
@@ -1324,6 +1453,61 @@ class MemoryServer {
             return { error: error.message || "Unknown error" };
         }
     }
+    async startSession(args) {
+        await this.initPromise;
+        const id = (0, uuid_1.v4)();
+        const now = Math.floor(Date.now() / 1000);
+        const name = args.name || `Session ${new Date().toISOString()}`;
+        // Create a Session entity first
+        await this.createEntity({
+            name,
+            type: "Session",
+            metadata: { session_id: id, ...args.metadata }
+        });
+        await this.db.run(`
+      ?[session_id, last_active, status, metadata] <- [[$id, $now, "active", $metadata]]
+      :insert session_state {session_id => last_active, status, metadata}
+    `, { id, now, metadata: args.metadata || {} });
+        return { id, name, status: "Session started" };
+    }
+    async stopSession(args) {
+        await this.initPromise;
+        await this.db.run(`
+      ?[session_id, last_active, status, metadata] :=
+        *session_state{session_id, last_active, metadata},
+        session_id = $id,
+        status = "closed"
+      :update session_state {session_id => last_active, status, metadata}
+    `, { id: args.id });
+        return { id: args.id, status: "Session closed" };
+    }
+    async startTask(args) {
+        await this.initPromise;
+        const id = (0, uuid_1.v4)();
+        const sessionId = args.session_id || "";
+        // Create a Task entity
+        await this.createEntity({
+            name: args.name,
+            type: "Task",
+            metadata: { task_id: id, session_id: sessionId, ...args.metadata }
+        });
+        await this.db.run(`
+      ?[task_id, status, session_id, metadata] <- [[$id, "active", $session, $metadata]]
+      :insert task_state {task_id => status, session_id, metadata}
+    `, { id, session: sessionId, metadata: args.metadata || {} });
+        return { id, name: args.name, session_id: sessionId, status: "Task started" };
+    }
+    async stopTask(args) {
+        await this.initPromise;
+        await this.db.run(`
+      ?[task_id, status, session_id, metadata] :=
+        *task_state{task_id, session_id, metadata},
+        task_id = $id,
+        status = "completed"
+      :update task_state {task_id => status, session_id, metadata}
+    `, { id: args.id });
+        return { id: args.id, status: "Task stopped" };
+    }
     async createRelation(args) {
         if (args.from_id === args.to_id) {
             return { error: "Self-references in relationships are not allowed" };
@@ -2162,14 +2346,16 @@ ids[id] <- $ids
                         const now = Date.now() * 1000;
                         allParams[`obs_id${suffix}`] = id;
                         allParams[`obs_entity_id${suffix}`] = entity_id;
+                        allParams[`obs_session_id${suffix}`] = params.session_id || "";
+                        allParams[`obs_task_id${suffix}`] = params.task_id || "";
                         allParams[`obs_text${suffix}`] = text || "";
                         allParams[`obs_embedding${suffix}`] = embedding;
                         allParams[`obs_metadata${suffix}`] = metadata || {};
                         statements.push(`
               {
-                ?[id, created_at, entity_id, text, embedding, metadata] <- [
-                  [$obs_id${suffix}, [${now}, true], $obs_entity_id${suffix}, $obs_text${suffix}, $obs_embedding${suffix}, $obs_metadata${suffix}]
-                ] :insert observation {id, created_at => entity_id, text, embedding, metadata}
+                ?[id, created_at, entity_id, session_id, task_id, text, embedding, metadata] <- [
+                  [$obs_id${suffix}, [${now}, true], $obs_entity_id${suffix}, $obs_session_id${suffix}, $obs_task_id${suffix}, $obs_text${suffix}, $obs_embedding${suffix}, $obs_metadata${suffix}]
+                ] :insert observation {id, created_at => entity_id, session_id, task_id, text, embedding, metadata}
               }
             `);
                         results.push({ action: "add_observation", id, entity_id });
@@ -2445,6 +2631,8 @@ ids[id] <- $ids
                 text: zod_1.z.string().describe("The fact or observation"),
                 metadata: MetadataSchema.optional().describe("Additional metadata"),
                 deduplicate: zod_1.z.boolean().optional().default(true).describe("Skip exact duplicates"),
+                session_id: zod_1.z.string().optional().describe("Associated session ID"),
+                task_id: zod_1.z.string().optional().describe("Associated task ID"),
             }).passthrough().refine((v) => Boolean(v.entity_id) || Boolean(v.entity_name), {
                 message: "entity_id or entity_name is required",
                 path: ["entity_id"],
@@ -2536,10 +2724,29 @@ ids[id] <- $ids
                 message: "file_path or content is required for ingest_file",
                 path: ["file_path"],
             }),
+            zod_1.z.object({
+                action: zod_1.z.literal("start_session"),
+                name: zod_1.z.string().optional().describe("Optional name for the session"),
+                metadata: MetadataSchema.optional().describe("Additional metadata"),
+            }).passthrough(),
+            zod_1.z.object({
+                action: zod_1.z.literal("stop_session"),
+                id: zod_1.z.string().describe("ID of the session to stop"),
+            }).passthrough(),
+            zod_1.z.object({
+                action: zod_1.z.literal("start_task"),
+                name: zod_1.z.string().describe("Name of the task"),
+                session_id: zod_1.z.string().optional().describe("Optional session ID this task belongs to"),
+                metadata: MetadataSchema.optional().describe("Additional metadata"),
+            }).passthrough(),
+            zod_1.z.object({
+                action: zod_1.z.literal("stop_task"),
+                id: zod_1.z.string().describe("ID of the task to stop"),
+            }).passthrough(),
         ]);
         const MutateMemoryParameters = zod_1.z.object({
             action: zod_1.z
-                .enum(["create_entity", "update_entity", "delete_entity", "add_observation", "create_relation", "run_transaction", "add_inference_rule", "ingest_file"])
+                .enum(["create_entity", "update_entity", "delete_entity", "add_observation", "create_relation", "run_transaction", "add_inference_rule", "ingest_file", "start_session", "stop_session", "start_task", "stop_task"])
                 .describe("Action (determines which fields are required)"),
             name: zod_1.z.string().optional().describe("For create_entity (required) or add_inference_rule (required)"),
             type: zod_1.z.string().optional().describe("For create_entity (required)"),
@@ -2587,6 +2794,10 @@ Supported actions:
   Example (Manager Transitivity):
   '?[from_id, to_id, relation_type, confidence, reason] := *relationship{from_id: $id, to_id: mid, relation_type: "manager_of", @ "NOW"}, *relationship{from_id: mid, to_id: target, relation_type: "manager_of", @ "NOW"}, from_id = $id, to_id = target, relation_type = "ober_manager_von", confidence = 0.6, reason = "Transitive Manager Path"'
 - 'ingest_file': Bulk import of documents (Markdown/JSON). Supports chunking (paragraphs) and automatic entity creation. Params: { entity_id | entity_name (required), format, content, ... }. Ideal for quickly populating memory from existing notes.
+- 'start_session': Initializes a new session for context tracking. Params: { name?: string, metadata?: object }.
+- 'stop_session': Closes a session. Params: { id: string }.
+- 'start_task': Initializes a new task within a session. Params: { name: string, session_id?: string, metadata?: object }.
+- 'stop_task': Marks a task as completed. Params: { id: string }.
 
 Validation: Invalid syntax or missing columns in inference rules will result in errors.`,
             parameters: MutateMemoryParameters,
@@ -2620,6 +2831,14 @@ Validation: Invalid syntax or missing columns in inference rules will result in
                     return JSON.stringify(await this.addInferenceRule(rest));
                 if (action === "ingest_file")
                     return JSON.stringify(await this.ingestFile(rest));
+                if (action === "start_session")
+                    return JSON.stringify(await this.startSession(rest));
+                if (action === "stop_session")
+                    return JSON.stringify(await this.stopSession(rest));
+                if (action === "start_task")
+                    return JSON.stringify(await this.startTask(rest));
+                if (action === "stop_task")
+                    return JSON.stringify(await this.stopTask(rest));
                 return JSON.stringify({ error: "Unknown action" });
             },
         });
@@ -2632,6 +2851,8 @@ Validation: Invalid syntax or missing columns in inference rules will result in
                 include_entities: zod_1.z.boolean().optional().default(true).describe("Include entities in search"),
                 include_observations: zod_1.z.boolean().optional().default(true).describe("Include observations in search"),
                 rerank: zod_1.z.boolean().optional().default(false).describe("Use Cross-Encoder reranking for higher precision"),
+                session_id: zod_1.z.string().optional().describe("Prioritize results from this session"),
+                task_id: zod_1.z.string().optional().describe("Prioritize results from this task"),
             }),
             zod_1.z.object({
                 action: zod_1.z.literal("advancedSearch"),
@@ -2660,6 +2881,8 @@ Validation: Invalid syntax or missing columns in inference rules will result in
                     efSearch: zod_1.z.number().optional().describe("HNSW search precision"),
                 }).optional().describe("Vector parameters"),
                 rerank: zod_1.z.boolean().optional().default(false).describe("Use Cross-Encoder reranking for higher precision"),
+                session_id: zod_1.z.string().optional().describe("Prioritize results from this session"),
+                task_id: zod_1.z.string().optional().describe("Prioritize results from this task"),
             }),
             zod_1.z.object({
                 action: zod_1.z.literal("context"),
@@ -2695,6 +2918,8 @@ Validation: Invalid syntax or missing columns in inference rules will result in
                 query: zod_1.z.string().describe("Context query for agentic routing"),
                 limit: zod_1.z.number().optional().default(10).describe("Maximum number of results"),
                 rerank: zod_1.z.boolean().optional().default(false).describe("Use Cross-Encoder reranking for higher precision"),
+                session_id: zod_1.z.string().optional().describe("Prioritize results from this session"),
+                task_id: zod_1.z.string().optional().describe("Prioritize results from this task"),
             }),
         ]);
         const QueryMemoryParameters = zod_1.z.object({
@@ -2703,6 +2928,8 @@ Validation: Invalid syntax or missing columns in inference rules will result in
                 .describe("Action (determines which fields are required)"),
             query: zod_1.z.string().optional().describe("Required for search/advancedSearch/context/graph_rag/graph_walking/agentic_search"),
             limit: zod_1.z.number().optional().describe("Only for search/advancedSearch/graph_rag/graph_walking"),
+            session_id: zod_1.z.string().optional().describe("Optional session ID for context boosting"),
+            task_id: zod_1.z.string().optional().describe("Optional task ID for context boosting"),
             filters: zod_1.z.any().optional().describe("Only for advancedSearch"),
             graphConstraints: zod_1.z.any().optional().describe("Only for advancedSearch"),
             vectorOptions: zod_1.z.any().optional().describe("Only for advancedSearch"),
@@ -2751,6 +2978,8 @@ Notes: 'agentic_search' is the most powerful and adaptable, 'context' is ideal f
                         includeEntities: input.include_entities,
                         includeObservations: input.include_observations,
                         rerank: input.rerank,
+                        session_id: input.session_id,
+                        task_id: input.task_id,
                     });
                     const conflictEntityIds = Array.from(new Set(results
                         .map((r) => (r.name ? r.id : r.entity_id))
@@ -2783,6 +3012,8 @@ Notes: 'agentic_search' is the most powerful and adaptable, 'context' is ideal f
                         graphConstraints: input.graphConstraints,
                         vectorParams: input.vectorParams,
                         rerank: input.rerank,
+                        session_id: input.session_id,
+                        task_id: input.task_id,
                     });
                     const conflictEntityIds = Array.from(new Set(results
                         .map((r) => (r.name ? r.id : r.entity_id))
@@ -3707,6 +3938,7 @@ Note: Use 'mutate_memory' with action='add_observation' and entity_id='global_us
         });
     }
     async start() {
+        await this.initPromise;
         await this.mcp.start({ transportType: "stdio" });
         console.error("Cozo Memory MCP Server running on stdio");
     }

package/dist/test-multi-level-memory.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+async function testMultiLevelMemory() {
+    console.log("=== Testing Multi-Level Memory (v2.0) ===\n");
+    const server = new index_1.MemoryServer();
+    await server.start();
+    try {
+        // 1. Session Management
+        console.log("--- 1. Testing Session Management ---");
+        const sessionRes = await server.startSession({ name: "Research Session", metadata: { user: "test_user" } });
+        const sessionId = sessionRes.id;
+        console.log(`Started session: ${sessionId}`);
+        // 2. Task Management
+        console.log("\n--- 2. Testing Task Management ---");
+        const taskRes = await server.startTask({ name: "Analyze Multi-Level Memory", session_id: sessionId });
+        const taskId = taskRes.id;
+        console.log(`Started task: ${taskId}`);
+        // 3. Observations with Context
+        console.log("\n--- 3. Adding observations with session and task IDs ---");
+        await server.addObservation({
+            entity_name: "Multi-Level Memory",
+            entity_type: "Concept",
+            text: "Multi-Level Memory is implemented in v2.0.",
+            session_id: sessionId,
+            task_id: taskId,
+            metadata: { importance: "high" }
+        });
+        console.log("Added observation for Multi-Level Memory with session and task context.");
+        await server.addObservation({
+            entity_name: "Janitor",
+            entity_type: "Service",
+            text: "Janitor now handles session compression.",
+            session_id: sessionId,
+            metadata: { importance: "medium" }
+        });
+        console.log("Added observation for Janitor with session context.");
+        // 4. Search with Context Boost
+        console.log("\n--- 4. Testing Context-Aware Search (Boosting) ---");
+        console.log("Case A: Search with session and task boost");
+        const searchResA = await server.advancedSearch({
+            query: "Multi-Level Memory",
+            session_id: sessionId,
+            task_id: taskId,
+            limit: 5
+        });
+        console.log("Search results (A):");
+        searchResA.forEach((r, i) => {
+            console.log(`  [${i + 1}] Score: ${r.score.toFixed(4)}, Text: ${r.text || r.name}, Explanation: ${r.explanation}`);
+        });
+        // 5. Session Compression
+        console.log("\n--- 5. Testing Session Compression (Janitor) ---");
+        console.log("Stopping session to prepare for compression...");
+        await server.stopSession({ id: sessionId });
+        console.log("Manually aging session activity in session_state table...");
+        const oldTs = Date.now() - 40 * 60 * 1000; // 40 minutes ago
+        await server['db'].run(`?[session_id, last_active, status, metadata] <- [[$id, $ts, 'open', $meta]]
+       :put session_state {session_id, last_active, status, metadata}`, { id: sessionId, ts: oldTs, meta: { user: "test_user" } });
+        console.log("Running Janitor cleanup with confirm=true...");
+        const janitorRes = await server.janitorCleanup({ confirm: true });
+        console.log("Janitor result:", JSON.stringify(janitorRes, null, 2));
+        // 6. Verify Compression Result
+        console.log("\n--- 6. Verifying compression summary in User Profile ---");
+        const profileRes = await server.advancedSearch({ query: "Session Summary", entityTypes: ["Observation"] });
+        console.log("Profile search results:");
+        profileRes.forEach((r, i) => {
+            if (r.text?.includes(sessionId)) {
+                console.log(`  [MATCH] ${r.text}`);
+            }
+        });
+        console.log("\n=== Multi-Level Memory Test completed successfully ===");
+    }
+    catch (error) {
+        console.error("Test failed:", error);
+    }
+    finally {
+        process.exit(0);
+    }
+}
+testMultiLevelMemory();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozo-memory",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "mcpName": "io.github.tobs-code/cozo-memory",
   "description": "Local-first persistent memory system for AI agents with hybrid search, graph reasoning, and MCP integration",
   "main": "dist/index.js",