squish-memory 0.8.2 → 0.9.2

package/scripts/verify-mcp.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+
+const root = process.cwd();
+const defaultConfigPath = path.join(root, "config", "mcp.json");
+const defaultGeneratedDir = path.join(root, "generated", "mcp");
+const requiredFiles = [
+  "runtime.json",
+  "mcp-servers.json",
+  "mcporter.json",
+  "openclaw-memory-qmd.json",
+  "manifest.json"
+];
+
+function parseArgs(argv) {
+  const args = {
+    configPath: defaultConfigPath,
+    generatedDir: defaultGeneratedDir,
+    checkReproducibility: true
+  };
+
+  for (let i = 2; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === "--config") {
+      args.configPath = path.resolve(argv[i + 1]);
+      i += 1;
+      continue;
+    }
+    if (token === "--generated") {
+      args.generatedDir = path.resolve(argv[i + 1]);
+      i += 1;
+      continue;
+    }
+    if (token === "--no-repro") {
+      args.checkReproducibility = false;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return args;
+}
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    fail(`Invalid JSON at ${filePath}: ${String(error)}`);
+  }
+}
+
+function checksum(filePath) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest("hex");
+}
+
+function assertServerShape(serverName, server) {
+  if (!server || typeof server !== "object") {
+    fail(`Server ${serverName} must be an object`);
+  }
+  if (typeof server.command !== "string" || server.command.length === 0) {
+    fail(`Server ${serverName} must include command`);
+  }
+  if (!Array.isArray(server.args)) {
+    fail(`Server ${serverName} must include args array`);
+  }
+  if (typeof server.transport !== "string" || server.transport.length === 0) {
+    fail(`Server ${serverName} must include transport`);
+  }
+  if (!server.env || typeof server.env !== "object") {
+    fail(`Server ${serverName} must include env object`);
+  }
+}
+
+function verifyGeneratedFiles(dirPath) {
+  for (const fileName of requiredFiles) {
+    const filePath = path.join(dirPath, fileName);
+    if (!fs.existsSync(filePath)) {
+      fail(`Missing generated file: ${fileName}`);
+    }
+  }
+}
+
+function verifyRuntime(runtime) {
+  const requiredKeys = [
+    "connectionTimeoutMs",
+    "requestTimeoutMs",
+    "maxConcurrentToolCalls",
+    "lazyToolDiscovery",
+    "resultMaxChars",
+    "retry"
+  ];
+  for (const key of requiredKeys) {
+    if (!(key in runtime)) {
+      fail(`runtime.json missing required key: ${key}`);
+    }
+  }
+}
+
+function verifyManifest(manifest, dirPath) {
+  if (manifest.mode !== "universal") {
+    fail("manifest mode must be universal");
+  }
+  if (!Array.isArray(manifest.files) || manifest.files.length === 0) {
+    fail("manifest files must be a non-empty array");
+  }
+
+  const expectedManifestEntries = [
+    "runtime.json",
+    "mcp-servers.json",
+    "mcporter.json",
+    "openclaw-memory-qmd.json"
+  ];
+
+  for (const fileName of expectedManifestEntries) {
+    const entry = manifest.files.find((item) => item.file === fileName);
+    if (!entry) {
+      fail(`manifest missing entry for ${fileName}`);
+    }
+    const actualHash = checksum(path.join(dirPath, fileName));
+    if (entry.sha256 !== actualHash) {
+      fail(`manifest checksum mismatch for ${fileName}`);
+    }
+  }
+}
+
+function verifyReproducibility(configPath, dirPath) {
+  const first = readJson(path.join(dirPath, "manifest.json"));
+  const firstChecksums = new Map(first.files.map((item) => [item.file, item.sha256]));
+
+  const run = spawnSync(
+    process.execPath,
+    ["scripts/generate-mcp.mjs", "--config", configPath, "--out", dirPath],
+    { cwd: root, encoding: "utf8" }
+  );
+
+  if (run.status !== 0) {
+    fail(`Reproducibility generation failed: ${run.stderr || run.stdout}`);
+  }
+
+  const second = readJson(path.join(dirPath, "manifest.json"));
+  const secondChecksums = new Map(second.files.map((item) => [item.file, item.sha256]));
+
+  for (const [fileName, firstHash] of firstChecksums.entries()) {
+    const secondHash = secondChecksums.get(fileName);
+    if (!secondHash) {
+      fail(`Reproducibility check missing ${fileName} in second manifest`);
+    }
+    if (firstHash !== secondHash) {
+      fail(`Reproducibility mismatch for ${fileName}`);
+    }
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+
+  if (!fs.existsSync(args.configPath)) {
+    fail(`Config file not found: ${args.configPath}`);
+  }
+  if (!fs.existsSync(args.generatedDir)) {
+    fail(`Generated directory not found: ${args.generatedDir}`);
+  }
+
+  verifyGeneratedFiles(args.generatedDir);
+
+  const runtime = readJson(path.join(args.generatedDir, "runtime.json"));
+  verifyRuntime(runtime);
+
+  const mcpServers = readJson(path.join(args.generatedDir, "mcp-servers.json"));
+  if (!mcpServers.mcpServers || typeof mcpServers.mcpServers !== "object") {
+    fail("mcp-servers.json must include mcpServers object");
+  }
+  const serverEntries = Object.entries(mcpServers.mcpServers);
+  if (serverEntries.length === 0) {
+    fail("mcp-servers.json must include at least one server");
+  }
+  for (const [name, server] of serverEntries) {
+    assertServerShape(name, server);
+  }
+
+  const mcporter = readJson(path.join(args.generatedDir, "mcporter.json"));
+  if (!Array.isArray(mcporter.imports) || mcporter.imports.length === 0) {
+    fail("mcporter.json must include imports array");
+  }
+  if (!mcporter.mcpServers || typeof mcporter.mcpServers !== "object") {
+    fail("mcporter.json must include mcpServers object");
+  }
+
+  const openclaw = readJson(path.join(args.generatedDir, "openclaw-memory-qmd.json"));
+  if (openclaw?.memory?.backend !== "qmd") {
+    fail("openclaw-memory-qmd.json must set memory.backend=qmd");
+  }
+
+  const manifest = readJson(path.join(args.generatedDir, "manifest.json"));
+  verifyManifest(manifest, args.generatedDir);
+
+  if (args.checkReproducibility) {
+    verifyReproducibility(args.configPath, args.generatedDir);
+  }
+
+  console.log("MCP verification passed");
+}
+
+main();

package/skills/memory-guide/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: memory-guide
-description: Expert guide for using Squish memory system v0.6.0. Use when managing persistent memory, storing context, recalling information, or optimizing memory usage in Claude Code sessions.
+description: Expert guide for using Squish memory system v0.9.0. Use when managing persistent memory, storing context, recalling information, or optimizing memory usage across MCP clients.
+version: 0.9.0
+author: michielhdoteth
+tags: [memory, persistence, squish, guide, mcp, ai-assistant]
+emoji: book
 ---
 
-# Squish Memory System Guide v0.6.0
+# Squish Memory System Guide v0.9.0
 
-You are an expert at using the Squish persistent memory system for Claude Code.
+You are an expert at using the Squish persistent memory system for AI coding assistants.
 
 ## When to Use Squish Memory
 
@@ -26,173 +30,227 @@ Use Squish memory tools proactively for:
    - Inject project-specific context
    - Maintain working memory across sessions
 
-## Core Memory (Always In Context)
+## MCP Tools Reference
 
-**Tool:** `core_memory` with `action` parameter
+### Storing Memories
 
-**Sections:**
-- **persona**: Your identity, role, communication style
-- **user_info**: User's name, preferences, coding style, expertise level
-- **project_context**: Current project context, architecture, stack, patterns
-- **working_notes**: Active TODOs, current focus, blockers, next steps
+**Tool:** `squish_remember`
 
-**Actions:**
-- `view` - See all core memory sections
-- `edit` - Replace content in a specific section
-- `append` - Add to existing section content
+Store new memories with automatic embedding.
 
-**When to update:**
-- Beginning of new projects (project_context section)
-- When user shares preferences (user_info section)
-- At end of sessions (working_notes section with TODOs)
-- When identity/role changes (persona section)
+```typescript
+// Store a preference
+squish_remember({
+  content: "User prefers functional components with hooks over class components",
+  type: "preference",
+  tags: ["react", "preferences"]
+})
 
-**Example usage:**
-```
-/squish:core_memory action=append section=project_context text="Stack: TypeScript, React, PostgreSQL, Drizzle ORM"
-/squish:core_memory action=edit section=working_notes content="Authentication complete. Next: implement API rate limiting"
-/squish:core_memory action=view
-```
+// Store a fact
+squish_remember({
+  content: "API uses JWT tokens with 1-hour expiration",
+  type: "fact",
+  tags: ["auth", "api"]
+})
 
-## Context Paging (Working Set)
+// Store a decision
+squish_remember({
+  content: "Chose PostgreSQL over MongoDB for better relational data",
+  type: "decision",
+  tags: ["database", "architecture"]
+})
+```
 
-**Tool:** `context_paging` with `action` parameter
+### Searching Memories
 
-**Purpose:** Agent-controlled working memory for relevant information during tasks
+**Tool:** `squish_search`
 
-**Actions:**
-- `load` - Load memories into working context
-- `evict` - Remove memories from working context
-- `view` - See what's currently loaded
+Hybrid search across all memory types.
 
-**When to load memories:**
-- Before starting work: Load relevant past decisions, patterns
-- During debugging: Load related error memories
-- For refactoring: Load architectural notes
+```typescript
+// Basic search
+squish_search({ query: "authentication patterns", limit: 5 })
 
-**When to evict:**
-- Task completed
-- Context getting full (check context_status)
-- Information no longer relevant
+// Search with project filter
+squish_search({ query: "database schema", project: "/path/to/project", limit: 10 })
 
-**Example workflow:**
+// Search specific memory type
+squish_search({ query: "user preferences", type: "preference" })
 ```
-# Before starting authentication work
-/squish:search query="authentication patterns we discussed"
-/squish:context_paging action=load memoryIds=["id1","id2","id3"]
 
-# Check what's loaded
-/squish:context_paging action=view
+### Retrieving Memories
 
-# After completing task
-/squish:context_paging action=evict memoryIds=["id1","id2"]
-```
+**Tool:** `squish_recall`
 
-## Storing Memories
+Retrieve a specific memory by ID.
 
-**Tool:** `remember`
+```typescript
+squish_recall({ memoryId: "uuid-here" })
+```
 
-**What to store:**
-- Decisions made and rationale
-- User preferences discovered
-- Code patterns agreed upon
-- Project-specific conventions
-- Blockers encountered and solutions
-- Technical specifications
+### Deleting Memories
 
-**Memory types:**
-- observation: Facts observed, patterns noticed
-- fact: Technical facts, specifications
-- decision: Decisions made with rationale
-- context: Project/domain context
-- preference: User preferences
+**Tool:** `squish_forget`
 
-**Example:**
-```
-/squish:remember content="User prefers functional components with hooks over class components" type=preference sector=autobiographical
-/squish:remember content="API uses JWT tokens with 1-hour expiration, refresh tokens stored in httpOnly cookies" type=fact sector=semantic
+Delete a memory by ID.
+
+```typescript
+squish_forget({ memoryId: "uuid-here" })
 ```
 
-## Search and Recall
+### Updating Memories
 
-**Tools:** `search`, `recall`, `get_related`
+**Tool:** `squish_update`
 
-**Search strategies:**
-- Semantic search: Natural language queries
-- Full-text search: Specific keywords, file names
-- Related memories: Find connected information via association graph
+Update existing memory content, tags, or type.
 
-**Example:**
-```
-/squish:search query="database schema design decisions" limit=5
-/squish:recall memoryId=abc123
-/squish:get_related memoryId=abc123 limit=10
+```typescript
+squish_update({
+  memoryId: "uuid-here",
+  content: "Updated content",
+  tags: ["new", "tags"],
+  type: "fact"
+})
 ```
 
-## Best Practices
+### Graph Associations
 
-1. **Store proactively**: Don't wait until end of session
-2. **Be specific**: Include context, timestamps, rationale
-3. **Use appropriate types**: Choose correct memory type and sector
-4. **Load selectively**: Don't load everything, focus on relevant memories
-5. **Maintain core memory**: Keep project/working sections current
-6. **Use associations**: Related memories are powerful for context
-
-## Memory Lifecycle
+**Tool:** `squish_associate`
 
-- **Hot memories**: Recent, frequently accessed (auto-retained)
-- **Warm memories**: Older but still relevant
-- **Cold memories**: Old, rarely accessed (may be evicted)
-- **Protected**: Marked important, won't be evicted
-- **Pinned**: Auto-injected into context
+Link related memories together.
 
-**Governance:**
-```
-/squish:protect_memory memoryId=abc123
-/squish:pin_memory memoryId=abc123
+```typescript
+squish_associate({
+  fromMemoryId: "uuid-1",
+  toMemoryId: "uuid-2",
+  type: "relates_to",
+  weight: 0.8
+})
 ```
 
-## Advanced Features
+**Tool:** `squish_related`
 
-**Merge duplicates:**
-```
-/squish:merge action=detect
-/squish:merge action=approve mergeId=xyz789
-```
+Find related memories via graph traversal.
 
-**Session summarization:**
-```
-/squish:summarize_session
+```typescript
+squish_related({
+  memoryId: "uuid-here",
+  depth: 2,
+  minWeight: 0.3
+})
 ```
 
-**Health check:**
+### Context & Observations
+
+**Tool:** `squish_context`
+
+Get project context with relevant memories.
+
+```typescript
+squish_context({ project: "/path/to/project", limit: 10 })
 ```
-/squish:health
+
+**Tool:** `squish_observe`
+
+Record observations about your work.
+
+```typescript
+squish_observe({
+  type: "tool_use",
+  action: "Created new API endpoint",
+  summary: "Implemented POST /users endpoint",
+  target: "api/users.ts"
+})
+
+squish_observe({
+  type: "error",
+  action: "Database connection failed",
+  summary: "PostgreSQL timeout after 30s",
+  target: "db/index.ts"
+})
 ```
 
-**Context status:**
+### QMD Search
+
+**Tool:** `squish_qmd_search`
+
+Search local markdown files using QMD.
+
+```typescript
+squish_qmd_search({ query: "authentication", limit: 10 })
+squish_qmd_search({ query: "react hooks", collection: "docs" })
 ```
-/squish:context_status
+
+### Utilities
+
+**Tool:** `squish_embed`
+
+Generate embeddings for text.
+
+```typescript
+squish_embed({ text: "Text to embed" })
 ```
 
-## Integration Pattern
+**Tool:** `squish_health`
+
+Check system health.
 
+```typescript
+squish_health({})
 ```
-1. Session start: /squish:core_memory action=view
-2. Load relevant context: /squish:search + /squish:context_paging action=load
-3. Work on task: Use loaded memories as reference
-4. Store new learnings: /squish:remember key information
-5. Update working memory: /squish:core_memory action=edit section=working_notes
-6. Session end: /squish:context_paging action=evict, summarize if needed
+
+**Tool:** `squish_stats`
+
+Get memory statistics.
+
+```typescript
+squish_stats({ project: "/path/to/project" })
 ```
 
-## v0.6.0 Changes
+**Tool:** `squish_projects`
+
+List all projects.
+
+```typescript
+squish_projects({})
+```
 
-**Consolidated Tools (11 tools, down from 18):**
-- `core_memory` - Replaces core_memory_view/edit/append
-- `context_paging` - Replaces load_to_context/evict_from_context/view_loaded
-- `merge` - Replaces detect_duplicates + merge operations
+## Best Practices
 
-**All tools now use `action` parameter for sub-operations.**
+1. **Store proactively**: Don't wait until end of session
+2. **Be specific**: Include context, timestamps, rationale
+3. **Use appropriate types**: Choose correct memory type and sector
+4. **Use associations**: Link related memories for better retrieval
+5. **Record observations**: Use `squish_observe` for tool usage patterns
+6. **Set importance**: Mark critical memories with high importance
+
+## Memory Types
+
+- **observation**: Facts observed, patterns noticed, tool usage
+- **fact**: Technical facts, specifications
+- **decision**: Decisions made with rationale
+- **context**: Project/domain context
+- **preference**: User preferences
+
+## When to Use Each Tool
+
+| Task | Use |
+|------|-----|
+| Remember something important | `squish_remember` |
+| Find relevant past info | `squish_search` |
+| Get specific memory | `squish_recall` |
+| Delete incorrect memory | `squish_forget` |
+| Update stored info | `squish_update` |
+| Link related memories | `squish_associate` |
+| Find connected info | `squish_related` |
+| Get project overview | `squish_context` |
+| Record work observations | `squish_observe` |
+| Search local docs | `squish_qmd_search` |
+| Check system status | `squish_health` |
+| View memory stats | `squish_stats` |
+
+## v0.9.0 Notes
+
+**All tools use consistent input schema patterns.**
 
 Remember: Squish is your persistent memory. Use it actively to maintain continuity across sessions and provide better assistance.