agent-working-memory 0.6.0 → 0.7.0

package/src/mcp.ts

@@ -26,7 +26,7 @@
 
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 // Load .env file if present (no external dependency)
 try {
@@ -42,6 +42,12 @@ try {
     if (!process.env[key]) process.env[key] = val;
   }
 } catch { /* No .env file */ }
+
+// MCP uses stdout for JSON-RPC. Redirect console.log to stderr so engine
+// startup messages (ConsolidationScheduler, model loading, etc.) don't
+// corrupt the transport. This MUST happen before any engine imports.
+console.log = console.error;
+
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 
@@ -62,6 +68,7 @@ import { DEFAULT_AGENT_CONFIG } from './types/agent.js';
 import { embed } from './core/embeddings.js';
 import { startSidecar } from './hooks/sidecar.js';
 import { initLogger, log, getLogPath } from './core/logger.js';
+import { queryPeerDecisions, formatPeerDecisions } from './coordination/peer-decisions.js';
 
 // --- Incognito Mode ---
 // When AWM_INCOGNITO=1, register zero tools. Claude won't see memory tools at all.
@@ -111,6 +118,58 @@ const server = new McpServer({
   version: '0.6.0',
 });
 
+server.registerResource(
+  'awm-overview',
+  'awm://server/overview',
+  {
+    title: 'AWM Overview',
+    description: 'AgentWorkingMemory MCP server metadata and discovery notes',
+    mimeType: 'text/markdown',
+  },
+  async () => ({
+    contents: [{
+      uri: 'awm://server/overview',
+      text: [
+        '# Agent Working Memory',
+        '',
+        `Agent: ${AGENT_ID}`,
+        `DB: ${DB_PATH}`,
+        `Coordination: ${process.env.AWM_COORDINATION === 'true' || process.env.AWM_COORDINATION === '1' ? 'enabled' : 'disabled'}`,
+        '',
+        'This MCP server primarily exposes tools such as `memory_restore`, `memory_recall`, `memory_write`, and task/checkpoint operations.',
+        'The resources below exist so generic MCP clients can discover the server through `resources/list` and `resources/templates/list`.',
+      ].join('\n'),
+      mimeType: 'text/markdown',
+    }],
+  })
+);
+
+server.registerResource(
+  'awm-memory-template',
+  new ResourceTemplate('awm://memory/{id}', { list: undefined }),
+  {
+    title: 'AWM Memory By ID',
+    description: 'Metadata resource template for a memory identifier',
+    mimeType: 'text/markdown',
+  },
+  async (_uri, variables) => ({
+    contents: [{
+      uri: `awm://memory/${variables.id ?? ''}`,
+      text: [
+        '# AWM Memory Reference',
+        '',
+        `Requested memory id: ${variables.id ?? ''}`,
+        '',
+        'Use the AWM memory tools for actual retrieval and mutation:',
+        '- `memory_recall` for cognitive retrieval',
+        '- `memory_restore` for session state',
+        '- `memory_feedback`, `memory_retract`, `memory_supersede` for memory maintenance',
+      ].join('\n'),
+      mimeType: 'text/markdown',
+    }],
+  })
+);
+
 // --- Auto-classification for memory types ---
 
 function classifyMemoryType(content: string): 'episodic' | 'semantic' | 'procedural' | 'unclassified' {
@@ -319,6 +378,7 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
     use_reranker: z.boolean().optional().default(true).describe('Use cross-encoder re-ranking for better relevance (default true)'),
     use_expansion: z.boolean().optional().default(true).describe('Expand query with synonyms for better recall (default true)'),
     memory_type: z.enum(['episodic', 'semantic', 'procedural']).optional().describe('Filter by memory type (omit to search all types)'),
+    workspace: z.string().optional().describe('Search across all agents in this workspace (hive mode). Omit for agent-scoped recall only.'),
   },
   async (params) => {
     const queryText = params.query ?? params.context;
@@ -330,6 +390,8 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
         }],
       };
     }
+    // Use workspace from param, env var, or omit for agent-scoped
+    const workspace = params.workspace ?? process.env.AWM_WORKSPACE ?? undefined;
     const results = await activationEngine.activate({
       agentId: AGENT_ID,
       context: queryText,
@@ -339,6 +401,7 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
       useReranker: params.use_reranker,
       useExpansion: params.use_expansion,
       memoryType: params.memory_type,
+      workspace,
     });
 
     // Auto-checkpoint: track recall
@@ -349,11 +412,16 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
 
     log(AGENT_ID, 'recall', `"${queryText.slice(0, 80)}" → ${results.length} results`);
 
+    // Peer decisions: append recent decisions by other agents relevant to this query
+    const peerSuffix = coordDb
+      ? formatPeerDecisions(queryPeerDecisions(coordDb, AGENT_ID, queryText))
+      : '';
+
     if (results.length === 0) {
       return {
         content: [{
           type: 'text' as const,
-          text: 'No relevant memories found.',
+          text: 'No relevant memories found.' + peerSuffix,
         }],
       };
     }
@@ -365,7 +433,7 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
     return {
       content: [{
         type: 'text' as const,
-        text: lines.join('\n'),
+        text: lines.join('\n') + peerSuffix,
       }],
     };
   }
@@ -392,10 +460,13 @@ Always call this after using a recalled memory so the system learns what's valua
       store.updateConfidence(engram.id, engram.confidence + delta);
     }
 
+    // Validation-gated Hebbian: resolve pending co-activation pairs for this engram
+    const hebbianUpdated = activationEngine.resolveHebbianFeedback(params.engram_id, params.useful);
+
     return {
       content: [{
         type: 'text' as const,
-        text: `Feedback: ${params.useful ? '+useful' : '-not useful'}`,
+        text: `Feedback: ${params.useful ? '+useful' : '-not useful'}${hebbianUpdated > 0 ? ` (${hebbianUpdated} association${hebbianUpdated > 1 ? 's' : ''} ${params.useful ? 'strengthened' : 'weakened'})` : ''}`,
       }],
     };
   }
@@ -609,6 +680,7 @@ Use this at the start of every session or after compaction to pick up where you
           minScore: 0.05,
           useReranker: true,
           useExpansion: true,
+          workspace: process.env.AWM_WORKSPACE ?? undefined,
         });
         recalledMemories = results.map(r => ({
           id: r.engram.id,
@@ -919,6 +991,7 @@ This ensures your state is saved before you start, and primes recall with releva
         minScore: 0.05,
         useReranker: true,
         useExpansion: true,
+        workspace: process.env.AWM_WORKSPACE ?? undefined,
       });
 
       if (results.length > 0) {

package/src/storage/sqlite.ts

@@ -30,6 +30,7 @@ const DEFAULT_SALIENCE_FEATURES: SalienceFeatures = {
 
 export class EngramStore {
   private db: Database.Database;
+  private walTimer: ReturnType<typeof setInterval> | null = null;
 
   constructor(dbPath: string = 'memory.db') {
     this.db = new Database(dbPath);
@@ -37,7 +38,9 @@ export class EngramStore {
     this.db.pragma('foreign_keys = ON');
     this.db.pragma('busy_timeout = 5000');
     this.db.pragma('synchronous = NORMAL');
+    this.db.pragma('wal_autocheckpoint = 1000');
     this.init();
+    this.startWalCheckpointTimer();
   }
 
   /** Expose the raw database handle for the coordination module. */
@@ -63,7 +66,27 @@ export class EngramStore {
 
   /** Flush WAL to main database file. */
   walCheckpoint(): void {
-    this.db.pragma('wal_checkpoint(TRUNCATE)');
+    try {
+      this.db.pragma('wal_checkpoint(TRUNCATE)');
+    } catch {
+      // Checkpoint can fail if another connection holds the DB; non-fatal
+    }
+  }
+
+  /** Start periodic WAL checkpoint every 5 minutes to prevent unbounded WAL growth. */
+  private startWalCheckpointTimer(): void {
+    this.walTimer = setInterval(() => {
+      this.walCheckpoint();
+    }, 5 * 60 * 1000);
+    this.walTimer.unref();
+  }
+
+  /** Stop the WAL checkpoint timer (call before close). */
+  stopWalCheckpointTimer(): void {
+    if (this.walTimer) {
+      clearInterval(this.walTimer);
+      this.walTimer = null;
+    }
   }
 
   private init(): void {
@@ -212,6 +235,13 @@ export class EngramStore {
       `);
     }
 
+    // Migration: add embedding_model for version tracking (prevents drift on model change)
+    try {
+      this.db.prepare('SELECT embedding_model FROM engrams LIMIT 0').get();
+    } catch {
+      this.db.exec(`ALTER TABLE engrams ADD COLUMN embedding_model TEXT`);
+    }
+
     // Migration: add conscious_state table for checkpointing
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS conscious_state (
@@ -299,6 +329,83 @@ export class EngramStore {
     return (this.db.prepare(query).all(...params) as any[]).map(r => this.rowToEngram(r));
   }
 
+  /**
+   * Get engrams across multiple agents (workspace-scoped recall).
+   * Used when workspace mode is enabled for hive memory sharing.
+   */
+  getEngramsByAgents(agentIds: string[], stage?: EngramStage, includeRetracted: boolean = false): Engram[] {
+    if (agentIds.length === 0) return [];
+    if (agentIds.length === 1) return this.getEngramsByAgent(agentIds[0], stage, includeRetracted);
+
+    const placeholders = agentIds.map(() => '?').join(',');
+    let query = `SELECT * FROM engrams WHERE agent_id IN (${placeholders})`;
+    const params: any[] = [...agentIds];
+
+    if (stage) {
+      query += ' AND stage = ?';
+      params.push(stage);
+    }
+    if (!includeRetracted) {
+      query += ' AND retracted = 0';
+    }
+
+    return (this.db.prepare(query).all(...params) as any[]).map(r => this.rowToEngram(r));
+  }
+
+  /**
+   * BM25 search across multiple agents (workspace-scoped).
+   */
+  searchBM25WithRankMultiAgent(agentIds: string[], query: string, limit: number = 10): { engram: Engram; bm25Score: number }[] {
+    if (agentIds.length === 0) return [];
+    if (agentIds.length === 1) return this.searchBM25WithRank(agentIds[0], query, limit);
+
+    const sanitized = query
+      .replace(/[^\w\s]/g, '')
+      .split(/\s+/)
+      .filter(w => w.length > 1)
+      .map(w => `"${w}"`)
+      .join(' OR ');
+
+    if (!sanitized) return [];
+
+    try {
+      const placeholders = agentIds.map(() => '?').join(',');
+      const rows = this.db.prepare(`
+        SELECT e.*, rank FROM engrams e
+        JOIN engrams_fts ON e.rowid = engrams_fts.rowid
+        WHERE engrams_fts MATCH ? AND e.agent_id IN (${placeholders}) AND e.retracted = 0
+        ORDER BY rank
+        LIMIT ?
+      `).all(sanitized, ...agentIds, limit) as any[];
+
+      return rows.map(r => ({
+        engram: this.rowToEngram(r),
+        bm25Score: Math.abs(r.rank ?? 0) / (1 + Math.abs(r.rank ?? 0)),
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Get all distinct agent IDs that share a workspace (requires coord_agents table).
+   * Returns just the queried agentId if coordination tables don't exist.
+   */
+  getWorkspaceAgentIds(agentId: string, workspace: string): string[] {
+    try {
+      const rows = this.db.prepare(
+        `SELECT DISTINCT id FROM coord_agents WHERE workspace = ? AND status != 'dead'`
+      ).all(workspace) as Array<{ id: string }>;
+      const ids = rows.map(r => r.id);
+      // Ensure the querying agent is always included
+      if (!ids.includes(agentId)) ids.push(agentId);
+      return ids;
+    } catch {
+      // No coordination tables — fall back to single agent
+      return [agentId];
+    }
+  }
+
   /**
    * Touch an engram: increment access count, update last_accessed, and
    * nudge confidence upward. Each retrieval is weak evidence the memory
@@ -327,9 +434,13 @@ export class EngramStore {
     );
   }
 
-  updateEmbedding(id: string, embedding: number[]): void {
+  updateEmbedding(id: string, embedding: number[], modelId?: string): void {
     const blob = Buffer.from(new Float32Array(embedding).buffer);
-    this.db.prepare('UPDATE engrams SET embedding = ? WHERE id = ?').run(blob, id);
+    if (modelId) {
+      this.db.prepare('UPDATE engrams SET embedding = ?, embedding_model = ? WHERE id = ?').run(blob, modelId, id);
+    } else {
+      this.db.prepare('UPDATE engrams SET embedding = ? WHERE id = ?').run(blob, id);
+    }
   }
 
   retractEngram(id: string, retractedBy: string | null): void {
@@ -1012,6 +1123,8 @@ export class EngramStore {
   }
 
   close(): void {
+    this.stopWalCheckpointTimer();
+    this.walCheckpoint();
     this.db.close();
   }
 }

package/src/types/engram.ts

@@ -186,6 +186,7 @@ export interface ActivationQuery {
   internal?: boolean;          // Skip access count increment, Hebbian update, and event logging (for system calls)
   memoryType?: MemoryType;     // Filter by memory type (episodic, semantic, procedural)
   mode?: QueryMode;            // Pipeline mode — 'auto' by default
+  workspace?: string;          // Search across all agents in this workspace (hive mode). If unset, agent-scoped only.
 }
 
 /**