cozo-memory 1.2.3 → 1.2.5

package/dist/index.js

@@ -2188,11 +2188,25 @@ ids[id] <- $ids
                 const actualHeaders = validationRes.headers;
                 const missingHeaders = expectedHeaders.filter(h => !actualHeaders.includes(h));
                 if (missingHeaders.length > 0) {
-                    return { error: `Invalid Datalog result set. Missing columns: ${missingHeaders.join(", ")}. Expected: ${expectedHeaders.join(", ")}` };
+                    return {
+                        error: `Invalid Datalog result set. Missing columns: ${missingHeaders.join(", ")}. Expected: ${expectedHeaders.join(", ")}`,
+                        hint: "Ensure all variables in the rule head are bound in the rule body. See docs/USAGE-GUIDE.md for examples."
+                    };
                 }
             }
             catch (validationError) {
-                return { error: `Datalog syntax error: ${validationError.message}` };
+                const errorMsg = validationError.message || String(validationError);
+                let hint = "";
+                if (errorMsg.includes("unbound")) {
+                    hint = "All variables in the rule head must appear in the rule body. Example: if you use 'relation_type' in the head, it must be bound to a value or extracted from a table in the body.";
+                }
+                else if (errorMsg.includes("syntax")) {
+                    hint = "Check Datalog syntax. Common issues: missing commas, incorrect table names, or malformed predicates.";
+                }
+                return {
+                    error: `Datalog syntax error: ${errorMsg}`,
+                    hint: hint || "See docs/USAGE-GUIDE.md for correct Datalog syntax and examples."
+                };
             }
             const id = (0, uuid_1.v4)();
             const now = Date.now();
@@ -3428,7 +3442,7 @@ Advanced: run_transaction, add_inference_rule, ingest_file, session/task managem
 
 Use entity_id='global_user_profile' for storing persistent user preferences (automatically boosted in searches).
 
-For detailed action descriptions, parameters, and examples, see the cozo-memory-guide steering file.
+For detailed action descriptions, parameters, and examples, see docs/USAGE-GUIDE.md.
 
 Note: Inference rules must return exactly 5 columns: [from_id, to_id, relation_type, confidence, reason]. Invalid syntax will result in errors.`,
             parameters: MutateMemoryParameters,
@@ -3778,9 +3792,17 @@ Note: Inference rules must return exactly 5 columns: [from_id, to_id, relation_t
 
 Use 'search' for quick lookups, 'adaptive_retrieval' for auto-optimization, or 'context' for comprehensive exploration.
 
-Available actions: search, advancedSearch, context, entity_details, history, graph_rag, graph_walking, adaptive_retrieval, dynamic_fusion, agentic_search, spreading_activation, suggest_connections, get_zettelkasten_stats, get_activation_stats, get_salience_stats, qafd_search, hierarchical_memory_query.
+Available actions:
+- search, advancedSearch: Hybrid search with query (required)
+- context: Context retrieval with query (required)
+- entity_details, history: Entity info with entity_id (required)
+- graph_rag, graph_walking: Graph traversal with query (required)
+- adaptive_retrieval, dynamic_fusion, agentic_search: Advanced search with query (required)
+- spreading_activation, qafd_search, hierarchical_memory_query: Specialized search with query (required)
+- suggest_connections: Connection suggestions with entity_id (required)
+- get_zettelkasten_stats, get_activation_stats, get_salience_stats: Statistics (no params required)
 
-Note: User profile observations (entity_id='global_user_profile') are automatically boosted in searches. For detailed action descriptions and parameters, see the cozo-memory-guide steering file.`,
+Note: User profile observations (entity_id='global_user_profile') are automatically boosted in searches. For detailed action descriptions and parameters, see docs/USAGE-GUIDE.md.`,
             parameters: QueryMemoryParameters,
             execute: async (args) => {
                 await this.initPromise;
@@ -4436,7 +4458,7 @@ Advanced: semantic_walk, infer_relations, bridge_discovery, hnsw_clusters, tempo
 
 Use 'explore' without end_entity for neighborhood, with end_entity for shortest path.
 
-For detailed action descriptions and parameters, see the cozo-memory-guide steering file.`,
+For detailed action descriptions and parameters, see docs/USAGE-GUIDE.md.`,
             parameters: AnalyzeGraphParameters,
             execute: async (args) => {
                 await this.initPromise;
@@ -4897,11 +4919,13 @@ Monitoring: health (status check), metrics (detailed stats)
 Data portability: export_memory (JSON/Markdown/Obsidian), import_memory (Mem0/MemGPT/Cozo)
 Backups: snapshot_create, snapshot_list, snapshot_diff
 Optimization: cleanup (LLM consolidation), defrag (merge duplicates), reflect (find contradictions)
-Advanced: summarize_communities, compress_memory_levels, analyze_memory_distribution
+Advanced: summarize_communities, compress_memory_levels, analyze_memory_distribution, compact
 
 Important: Use confirm=false for dry-run before cleanup/defrag. clear_memory requires confirm=true.
 
-For detailed action descriptions and parameters, see the cozo-memory-guide steering file.`,
+Note: For statistics (get_salience_stats, get_activation_stats, get_zettelkasten_stats), use query_memory tool instead.
+
+For detailed action descriptions and parameters, see docs/USAGE-GUIDE.md.`,
             parameters: ManageSystemParameters,
             execute: async (args) => {
                 await this.initPromise;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozo-memory",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "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",