cozo-memory 1.0.5 → 1.0.7

package/README.md

@@ -83,6 +83,10 @@ Now you can add the server to your MCP client (e.g. Claude Desktop).
 
 📦 **Export/Import (since v1.8)** - Export to JSON, Markdown, or Obsidian-ready ZIP; import from Mem0, MemGPT, Markdown, or native format
 
+📄 **PDF Support (since v1.9)** - Direct PDF ingestion with text extraction via pdfjs-dist; supports file path and content parameters
+
+🕐 **Dual Timestamp Format (since v1.9)** - All timestamps returned in both Unix microseconds and ISO 8601 format for maximum flexibility
+
 ### Detailed Features
 - **Hybrid Search (v0.7 Optimized)**: Combination of semantic search (HNSW), **Full-Text Search (FTS)**, and graph signals, merged via Reciprocal Rank Fusion (RRF).
 - **Full-Text Search (FTS)**: Native CozoDB v0.7 FTS indices with stemming, stopword filtering, and robust query sanitizing (cleaning of `+ - * / \ ( ) ? .`) for maximum stability.
@@ -331,6 +335,67 @@ npm run start
 
 Default database path: `memory_db.cozo.db` in project root (created automatically).
 
+### CLI Tool
+
+CozoDB Memory includes a full-featured CLI for all operations:
+
+```bash
+# System operations
+cozo-memory system health
+cozo-memory system metrics
+
+# Entity operations
+cozo-memory entity create -n "MyEntity" -t "person" -m '{"age": 30}'
+cozo-memory entity get -i <entity-id>
+cozo-memory entity delete -i <entity-id>
+
+# Observations
+cozo-memory observation add -i <entity-id> -t "Some note"
+
+# Relations
+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"
+
+# Graph operations
+cozo-memory graph explore -s <entity-id> -h 3
+cozo-memory graph pagerank
+cozo-memory graph communities
+
+# Export/Import
+cozo-memory export json -o backup.json --include-metadata --include-relationships --include-observations
+cozo-memory export markdown -o notes.md
+cozo-memory export obsidian -o vault.zip
+cozo-memory import file -i data.json -f cozo
+
+# All commands support -f json or -f pretty for output formatting
+```
+
+### TUI (Terminal User Interface)
+
+Interactive TUI with mouse support powered by Python Textual:
+
+```bash
+# Install Python dependencies (one-time)
+pip install textual
+
+# Launch TUI
+npm run tui
+# or directly:
+cozo-memory-tui
+```
+
+**TUI Features:**
+- 🖱️ Full mouse support (click buttons, scroll, select inputs)
+- ⌨️ Keyboard shortcuts (q=quit, h=help, r=refresh)
+- 📊 Interactive menus for all operations
+- 🎨 Rich terminal UI with colors and animations
+- 📋 Real-time results display
+- 🔍 Forms for entity creation, search, graph operations
+- 📤 Export/Import wizards
+
 ### Claude Desktop Integration
 
 #### Using npx (Recommended)
@@ -746,6 +811,24 @@ Returns deletion statistics showing exactly what was removed.
 
 ## Technical Highlights
 
+### Dual Timestamp Format (v1.9)
+
+All write operations (`create_entity`, `add_observation`, `create_relation`) return timestamps in both formats:
+- `created_at`: Unix microseconds (CozoDB native format, precise for calculations)
+- `created_at_iso`: ISO 8601 string (human-readable, e.g., `"2026-02-28T17:21:19.343Z"`)
+
+This dual format provides maximum flexibility - use Unix timestamps for time calculations and comparisons, or ISO strings for display and logging.
+
+Example response:
+```json
+{
+  "id": "...",
+  "created_at": 1772299279343000,
+  "created_at_iso": "2026-02-28T17:21:19.343Z",
+  "status": "Entity created"
+}
+```
+
 ### Local ONNX Embeddings (Transformers)
 
 Default Model: `Xenova/bge-m3` (1024 dimensions).
@@ -829,6 +912,42 @@ The system maintains a persistent profile of the user (preferences, dislikes, wo
 - **Mechanism**: All observations assigned to this entity receive a significant boost in search and context queries.
 - **Initialization**: The profile is automatically created on first start.
 
+### Manual Profile Editing
+
+You can now directly edit the user profile using the `edit_user_profile` MCP tool:
+
+```typescript
+// View current profile
+{ }
+
+// Update metadata
+{ 
+  metadata: { timezone: "Europe/Berlin", language: "de" } 
+}
+
+// Add preferences
+{ 
+  observations: [
+    { text: "Prefers TypeScript over JavaScript" },
+    { text: "Likes concise documentation" }
+  ]
+}
+
+// Clear and reset preferences
+{ 
+  clear_observations: true,
+  observations: [{ text: "New preference" }]
+}
+
+// Update name and type
+{ 
+  name: "Developer Profile", 
+  type: "UserProfile" 
+}
+```
+
+**Note**: You can still use the implicit method via `mutate_memory` with `action='add_observation'` and `entity_id='global_user_profile'`.
+
 ### Manual Tests
 
 There are various test scripts for different features:
@@ -845,6 +964,9 @@ npx ts-node test-reflection.ts
 
 # Tests user preference profiling and search boost
 npx ts-node test-user-pref.ts
+
+# Tests manual user profile editing
+npx ts-node src/test-user-profile.ts
 ```
 
 ## Troubleshooting

package/dist/api_bridge.js

@@ -35,11 +35,13 @@ app.post("/api/entities", async (req, res) => {
     try {
         // We use the same logic as in create_entity tool
         const id = (0, uuid_1.v4)();
-        const embedding = await memoryServer.embeddingService.embed(name + " " + type);
+        const content = name + " " + type;
+        const embedding = await memoryServer.embeddingService.embed(content);
+        const nameEmbedding = await memoryServer.embeddingService.embed(name);
         await memoryServer.db.run(`
-        ?[id, created_at, name, type, embedding, metadata] <- [
-          [$id, "ASSERT", $name, $type, [${embedding.join(",")}], $metadata]
-        ] :put entity {id, created_at => name, type, embedding, metadata}
+        ?[id, created_at, name, type, embedding, name_embedding, metadata] <- [
+          [$id, "ASSERT", $name, $type, [${embedding.join(",")}], [${nameEmbedding.join(",")}], $metadata]
+        ] :put entity {id, created_at => name, type, embedding, name_embedding, metadata}
       `, { id, name, type, metadata: metadata || {} });
         res.status(201).json({ id, name, type, metadata, status: "Entity created" });
     }

package/dist/cli-commands.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Shared CLI command logic for both pure CLI and TUI
+ * Calls MemoryServer public methods directly
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLICommands = void 0;
+const index_js_1 = require("./index.js");
+class CLICommands {
+    server;
+    initialized = false;
+    constructor() {
+        this.server = new index_js_1.MemoryServer();
+    }
+    async init() {
+        if (!this.initialized) {
+            await this.server.initPromise;
+            this.initialized = true;
+        }
+    }
+    async close() {
+        // CozoDB handles cleanup automatically
+    }
+    // Entity operations - use db directly
+    async createEntity(name, type, metadata) {
+        const { v4: uuidv4 } = await import('uuid');
+        const id = uuidv4();
+        const content = name + " " + type;
+        const embedding = await this.server.embeddingService.embed(content);
+        const nameEmbedding = await this.server.embeddingService.embed(name);
+        const now = Date.now() * 1000; // microseconds
+        const nowIso = new Date().toISOString();
+        await this.server.db.run(`
+        ?[id, created_at, name, type, embedding, name_embedding, metadata] <- [
+          [$id, "ASSERT", $name, $type, [${embedding.join(",")}], [${nameEmbedding.join(",")}], $metadata]
+        ] :put entity {id, created_at => name, type, embedding, name_embedding, metadata}
+      `, { id, name, type, metadata: metadata || {} });
+        return { id, name, type, metadata, created_at: now, created_at_iso: nowIso, status: "Entity created" };
+    }
+    async getEntity(entityId) {
+        const entityRes = await this.server.db.run('?[id, name, type, metadata, ts] := *entity{id, name, type, metadata, created_at, @ "NOW"}, id = $id, ts = to_int(created_at)', { id: entityId });
+        if (entityRes.rows.length === 0) {
+            throw new Error("Entity not found");
+        }
+        const obsRes = await this.server.db.run('?[id, text, metadata, ts] := *observation{id, entity_id, text, metadata, created_at, @ "NOW"}, entity_id = $id, ts = to_int(created_at)', { id: entityId });
+        const relRes = await this.server.db.run(`
+        ?[target_id, type, strength, metadata, direction] := *relationship{from_id, to_id, relation_type: type, strength, metadata, @ "NOW"}, from_id = $id, target_id = to_id, direction = 'outgoing'
+        ?[target_id, type, strength, metadata, direction] := *relationship{from_id, to_id, relation_type: type, strength, metadata, @ "NOW"}, to_id = $id, target_id = from_id, direction = 'incoming'
+      `, { id: entityId });
+        return {
+            entity: {
+                id: entityRes.rows[0][0],
+                name: entityRes.rows[0][1],
+                type: entityRes.rows[0][2],
+                metadata: entityRes.rows[0][3],
+                created_at: entityRes.rows[0][4]
+            },
+            observations: obsRes.rows.map((r) => ({ id: r[0], text: r[1], metadata: r[2], created_at: r[3] })),
+            relations: relRes.rows.map((r) => ({ target_id: r[0], type: r[1], strength: r[2], metadata: r[3], direction: r[4] }))
+        };
+    }
+    async deleteEntity(entityId) {
+        await this.server.db.run(`
+        { ?[id, created_at] := *observation{id, entity_id, created_at}, entity_id = $target_id :rm observation {id, created_at} }
+        { ?[from_id, to_id, relation_type, created_at] := *relationship{from_id, to_id, relation_type, created_at}, from_id = $target_id :rm relationship {from_id, to_id, relation_type, created_at} }
+        { ?[from_id, to_id, relation_type, created_at] := *relationship{from_id, to_id, relation_type, created_at}, to_id = $target_id :rm relationship {from_id, to_id, relation_type, created_at} }
+        { ?[id, created_at] := *entity{id, created_at}, id = $target_id :rm entity {id, created_at} }
+      `, { target_id: entityId });
+        return { status: "Entity and related data deleted" };
+    }
+    // Observation operations
+    async addObservation(entityId, text, metadata) {
+        const { v4: uuidv4 } = await import('uuid');
+        const id = uuidv4();
+        const embedding = await this.server.embeddingService.embed(text);
+        const now = Date.now() * 1000;
+        const nowIso = new Date().toISOString();
+        await this.server.db.run(`
+        ?[id, created_at, entity_id, text, embedding, metadata] <- [
+          [$id, "ASSERT", $entity_id, $text, [${embedding.join(",")}], $metadata]
+        ] :put observation {id, created_at => entity_id, text, embedding, metadata}
+      `, { id, entity_id: entityId, text, metadata: metadata || {} });
+        return { id, entity_id: entityId, text, metadata, created_at: now, created_at_iso: nowIso, status: "Observation added" };
+    }
+    // Relation operations
+    async createRelation(fromId, toId, relationType, strength, metadata) {
+        const str = strength !== undefined ? strength : 1.0;
+        const now = Date.now() * 1000;
+        const nowIso = new Date().toISOString();
+        await this.server.db.run(`
+        ?[from_id, to_id, relation_type, created_at, strength, metadata] <- [
+          [$from_id, $to_id, $relation_type, "ASSERT", $strength, $metadata]
+        ] :put relationship {from_id, to_id, relation_type, created_at => strength, metadata}
+      `, { from_id: fromId, to_id: toId, relation_type: relationType, strength: str, metadata: metadata || {} });
+        return { from_id: fromId, to_id: toId, relation_type: relationType, strength: str, metadata, created_at: now, created_at_iso: nowIso, status: "Relation created" };
+    }
+    // Search operations - use the MCP tool directly
+    async search(query, limit = 10, entityTypes, includeEntities = true, includeObservations = true) {
+        // Call the search method from the server's query_memory tool
+        const result = await this.server.hybridSearch.search({
+            query,
+            limit,
+            entityTypes,
+            includeEntities,
+            includeObservations
+        });
+        // If result is empty or has issues, return it as-is
+        return result;
+    }
+    async advancedSearch(params) {
+        return await this.server.advancedSearch(params);
+    }
+    async context(query, contextWindow, timeRangeHours) {
+        // Use advancedSearch with appropriate parameters
+        return await this.server.advancedSearch({
+            query,
+            limit: contextWindow || 10,
+            timeRangeHours
+        });
+    }
+    // Graph operations
+    async explore(startEntity, endEntity, maxHops, relationTypes) {
+        // Use graph_walking or advancedSearch
+        if (endEntity) {
+            // Path finding
+            return await this.server.computeShortestPath({
+                start_entity: startEntity,
+                end_entity: endEntity
+            });
+        }
+        else {
+            // Graph exploration - use advancedSearch with graph constraints
+            return await this.server.advancedSearch({
+                query: '',
+                graphConstraints: {
+                    maxDepth: maxHops || 3,
+                    requiredRelations: relationTypes,
+                    targetEntityIds: [startEntity]
+                }
+            });
+        }
+    }
+    async pagerank() {
+        return await this.server.recomputePageRank();
+    }
+    async communities() {
+        return await this.server.recomputeCommunities();
+    }
+    // System operations
+    async health() {
+        const entityCount = await this.server.db.run('?[count(id)] := *entity{id, @ "NOW"}');
+        const obsCount = await this.server.db.run('?[count(id)] := *observation{id, @ "NOW"}');
+        const relCount = await this.server.db.run('?[count(from_id)] := *relationship{from_id, @ "NOW"}');
+        return {
+            status: "healthy",
+            entities: entityCount.rows[0][0],
+            observations: obsCount.rows[0][0],
+            relationships: relCount.rows[0][0]
+        };
+    }
+    async metrics() {
+        // Access private metrics via type assertion
+        return this.server.metrics;
+    }
+    async exportMemory(format, options) {
+        const { ExportImportService } = await import('./export-import-service.js');
+        // Create a simple wrapper that implements DbService interface
+        const dbService = {
+            run: async (query, params) => {
+                return await this.server.db.run(query, params);
+            }
+        };
+        const exportService = new ExportImportService(dbService);
+        return await exportService.exportMemory({
+            format,
+            includeMetadata: options?.includeMetadata,
+            includeRelationships: options?.includeRelationships,
+            includeObservations: options?.includeObservations,
+            entityTypes: options?.entityTypes,
+            since: options?.since
+        });
+    }
+    async importMemory(data, sourceFormat, options) {
+        const { ExportImportService } = await import('./export-import-service.js');
+        // Create a simple wrapper that implements DbService interface
+        const dbService = {
+            run: async (query, params) => {
+                return await this.server.db.run(query, params);
+            }
+        };
+        const exportService = new ExportImportService(dbService);
+        return await exportService.importMemory(data, {
+            sourceFormat: sourceFormat,
+            mergeStrategy: options?.mergeStrategy || 'skip',
+            defaultEntityType: options?.defaultEntityType
+        });
+    }
+    async ingestFile(entityId, format, filePath, content, options) {
+        // This would need to be implemented similar to the MCP tool
+        // For now, return a placeholder
+        return { status: "not_implemented", message: "Use MCP server for file ingestion" };
+    }
+    async editUserProfile(args) {
+        return await this.server.editUserProfile(args);
+    }
+    async getUserProfile() {
+        return await this.server.editUserProfile({});
+    }
+}
+exports.CLICommands = CLICommands;