@agent-receipts/dashboard 0.2.11 → 0.3.1

package/standalone/packages/mcp-server/dist/index.js

@@ -135,6 +135,9 @@ var SqliteReceiptStore = class {
       data: JSON.stringify(receipt)
     };
   }
+  getDb() {
+    return this.db;
+  }
   async save(receipt) {
     const row = this.toRow(receipt);
     this.db.prepare(`INSERT OR REPLACE INTO receipts (
@@ -474,6 +477,583 @@ var ConfigManager = class {
   }
 };
 
+// src/storage/memory-store.ts
+var CONFIDENCE_ORDER = {
+  certain: 5,
+  high: 4,
+  medium: 3,
+  low: 2,
+  deprecated: 1
+};
+var MemoryStore = class {
+  constructor(db) {
+    this.db = db;
+  }
+  init() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS entities (
+        entity_id TEXT PRIMARY KEY,
+        entity_type TEXT NOT NULL,
+        name TEXT NOT NULL,
+        aliases TEXT NOT NULL DEFAULT '[]',
+        scope TEXT NOT NULL DEFAULT 'agent',
+        created_at TEXT NOT NULL,
+        created_by_agent TEXT NOT NULL,
+        created_by_receipt TEXT NOT NULL,
+        forgotten_at TEXT,
+        merged_into TEXT,
+        attributes TEXT NOT NULL DEFAULT '{}',
+        metadata TEXT NOT NULL DEFAULT '{}'
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(entity_type);
+      CREATE INDEX IF NOT EXISTS idx_entities_name ON entities(name);
+      CREATE INDEX IF NOT EXISTS idx_entities_scope ON entities(scope);
+      CREATE INDEX IF NOT EXISTS idx_entities_agent ON entities(created_by_agent);
+      CREATE INDEX IF NOT EXISTS idx_entities_forgotten ON entities(forgotten_at);
+
+      CREATE TABLE IF NOT EXISTS observations (
+        observation_id TEXT PRIMARY KEY,
+        entity_id TEXT NOT NULL,
+        content TEXT NOT NULL,
+        confidence TEXT NOT NULL DEFAULT 'medium',
+        source_receipt_id TEXT NOT NULL,
+        source_agent_id TEXT NOT NULL,
+        source_context TEXT,
+        observed_at TEXT NOT NULL,
+        forgotten_at TEXT,
+        forgotten_by TEXT,
+        superseded_by TEXT,
+        expires_at TEXT,
+        tags TEXT NOT NULL DEFAULT '[]',
+        metadata TEXT NOT NULL DEFAULT '{}',
+        FOREIGN KEY (entity_id) REFERENCES entities(entity_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_obs_entity ON observations(entity_id);
+      CREATE INDEX IF NOT EXISTS idx_obs_agent ON observations(source_agent_id);
+      CREATE INDEX IF NOT EXISTS idx_obs_confidence ON observations(confidence);
+      CREATE INDEX IF NOT EXISTS idx_obs_forgotten ON observations(forgotten_at);
+      CREATE INDEX IF NOT EXISTS idx_obs_receipt ON observations(source_receipt_id);
+      CREATE INDEX IF NOT EXISTS idx_obs_expires ON observations(expires_at);
+
+      CREATE TABLE IF NOT EXISTS relationships (
+        relationship_id TEXT PRIMARY KEY,
+        from_entity_id TEXT NOT NULL,
+        to_entity_id TEXT NOT NULL,
+        relationship_type TEXT NOT NULL,
+        strength TEXT NOT NULL DEFAULT 'medium',
+        source_receipt_id TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        forgotten_at TEXT,
+        metadata TEXT NOT NULL DEFAULT '{}',
+        FOREIGN KEY (from_entity_id) REFERENCES entities(entity_id),
+        FOREIGN KEY (to_entity_id) REFERENCES entities(entity_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_rel_from ON relationships(from_entity_id);
+      CREATE INDEX IF NOT EXISTS idx_rel_to ON relationships(to_entity_id);
+      CREATE INDEX IF NOT EXISTS idx_rel_type ON relationships(relationship_type);
+    `);
+    try {
+      this.db.exec("ALTER TABLE observations ADD COLUMN expires_at TEXT");
+    } catch {
+    }
+    try {
+      this.db.exec(`
+        CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
+          content,
+          content='observations',
+          content_rowid='rowid',
+          tokenize='porter unicode61'
+        );
+      `);
+    } catch {
+    }
+    this.db.exec(`
+      CREATE TRIGGER IF NOT EXISTS observations_ai AFTER INSERT ON observations BEGIN
+        INSERT INTO observations_fts(rowid, content) VALUES (new.rowid, new.content);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS observations_ad AFTER DELETE ON observations BEGIN
+        INSERT INTO observations_fts(observations_fts, rowid, content) VALUES('delete', old.rowid, old.content);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS observations_au AFTER UPDATE ON observations BEGIN
+        INSERT INTO observations_fts(observations_fts, rowid, content) VALUES('delete', old.rowid, old.content);
+        INSERT INTO observations_fts(rowid, content) VALUES (new.rowid, new.content);
+      END;
+    `);
+  }
+  // --- Entities ---
+  createEntity(entity) {
+    this.db.prepare(`
+      INSERT INTO entities (entity_id, entity_type, name, aliases, scope, created_at,
+        created_by_agent, created_by_receipt, forgotten_at, merged_into, attributes, metadata)
+      VALUES (@entity_id, @entity_type, @name, @aliases, @scope, @created_at,
+        @created_by_agent, @created_by_receipt, @forgotten_at, @merged_into, @attributes, @metadata)
+    `).run({
+      entity_id: entity.entity_id,
+      entity_type: entity.entity_type,
+      name: entity.name,
+      aliases: JSON.stringify(entity.aliases),
+      scope: entity.scope,
+      created_at: entity.created_at,
+      created_by_agent: entity.created_by_agent,
+      created_by_receipt: entity.created_by_receipt,
+      forgotten_at: entity.forgotten_at,
+      merged_into: entity.merged_into,
+      attributes: JSON.stringify(entity.attributes),
+      metadata: JSON.stringify(entity.metadata)
+    });
+    return entity;
+  }
+  getEntity(entityId) {
+    const row = this.db.prepare("SELECT * FROM entities WHERE entity_id = ?").get(entityId);
+    if (!row) return null;
+    return this.rowToEntity(row);
+  }
+  findEntityByName(name, entityType) {
+    const row = this.db.prepare(
+      "SELECT * FROM entities WHERE name = ? AND entity_type = ? AND forgotten_at IS NULL AND merged_into IS NULL"
+    ).get(name, entityType);
+    if (!row) return null;
+    return this.rowToEntity(row);
+  }
+  findEntities(query) {
+    const conditions = [];
+    const params = [];
+    if (!query.include_forgotten) {
+      conditions.push("forgotten_at IS NULL");
+      conditions.push("merged_into IS NULL");
+    }
+    if (query.entity_type) {
+      conditions.push("entity_type = ?");
+      params.push(query.entity_type);
+    }
+    if (query.scope) {
+      conditions.push("scope = ?");
+      params.push(query.scope);
+    }
+    if (query.agent_id) {
+      conditions.push("created_by_agent = ?");
+      params.push(query.agent_id);
+    }
+    if (query.query) {
+      conditions.push("(name LIKE ? OR aliases LIKE ?)");
+      const pattern = `%${query.query}%`;
+      params.push(pattern, pattern);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = query.limit ?? 20;
+    const page = query.page ?? 1;
+    const offset = (page - 1) * limit;
+    const countRow = this.db.prepare(`SELECT COUNT(*) as cnt FROM entities ${where}`).get(...params);
+    const total = countRow.cnt;
+    const totalPages = Math.max(1, Math.ceil(total / limit));
+    const rows = this.db.prepare(
+      `SELECT * FROM entities ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`
+    ).all(...params, limit, offset);
+    return {
+      data: rows.map((r) => this.rowToEntity(r)),
+      pagination: {
+        page,
+        limit,
+        total,
+        total_pages: totalPages,
+        has_next: page < totalPages,
+        has_prev: page > 1
+      }
+    };
+  }
+  updateEntity(entityId, updates) {
+    const existing = this.getEntity(entityId);
+    if (!existing) throw new Error(`Entity not found: ${entityId}`);
+    const updated = { ...existing, ...updates };
+    this.db.prepare(`
+      UPDATE entities SET
+        name = @name, aliases = @aliases, scope = @scope,
+        attributes = @attributes, metadata = @metadata,
+        forgotten_at = @forgotten_at, merged_into = @merged_into
+      WHERE entity_id = @entity_id
+    `).run({
+      entity_id: entityId,
+      name: updated.name,
+      aliases: JSON.stringify(updated.aliases),
+      scope: updated.scope,
+      attributes: JSON.stringify(updated.attributes),
+      metadata: JSON.stringify(updated.metadata),
+      forgotten_at: updated.forgotten_at,
+      merged_into: updated.merged_into
+    });
+    return this.getEntity(entityId);
+  }
+  forgetEntity(entityId, agentId) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    this.db.prepare("UPDATE entities SET forgotten_at = ? WHERE entity_id = ?").run(now, entityId);
+    this.db.prepare("UPDATE observations SET forgotten_at = ?, forgotten_by = ? WHERE entity_id = ? AND forgotten_at IS NULL").run(now, agentId, entityId);
+  }
+  mergeEntities(sourceId, targetId) {
+    const source = this.getEntity(sourceId);
+    const target = this.getEntity(targetId);
+    if (!source) throw new Error(`Source entity not found: ${sourceId}`);
+    if (!target) throw new Error(`Target entity not found: ${targetId}`);
+    this.db.prepare("UPDATE observations SET entity_id = ? WHERE entity_id = ?").run(targetId, sourceId);
+    this.db.prepare("UPDATE relationships SET from_entity_id = ? WHERE from_entity_id = ?").run(targetId, sourceId);
+    this.db.prepare("UPDATE relationships SET to_entity_id = ? WHERE to_entity_id = ?").run(targetId, sourceId);
+    const mergedAliases = [.../* @__PURE__ */ new Set([...target.aliases, source.name, ...source.aliases])];
+    this.db.prepare("UPDATE entities SET aliases = ? WHERE entity_id = ?").run(JSON.stringify(mergedAliases), targetId);
+    this.db.prepare("UPDATE entities SET merged_into = ?, forgotten_at = ? WHERE entity_id = ?").run(targetId, (/* @__PURE__ */ new Date()).toISOString(), sourceId);
+    return this.getEntity(targetId);
+  }
+  // --- Observations ---
+  addObservation(obs) {
+    this.db.prepare(`
+      INSERT INTO observations (observation_id, entity_id, content, confidence,
+        source_receipt_id, source_agent_id, source_context, observed_at,
+        forgotten_at, forgotten_by, superseded_by, expires_at, tags, metadata)
+      VALUES (@observation_id, @entity_id, @content, @confidence,
+        @source_receipt_id, @source_agent_id, @source_context, @observed_at,
+        @forgotten_at, @forgotten_by, @superseded_by, @expires_at, @tags, @metadata)
+    `).run({
+      observation_id: obs.observation_id,
+      entity_id: obs.entity_id,
+      content: obs.content,
+      confidence: obs.confidence,
+      source_receipt_id: obs.source_receipt_id,
+      source_agent_id: obs.source_agent_id,
+      source_context: obs.source_context,
+      observed_at: obs.observed_at,
+      forgotten_at: obs.forgotten_at,
+      forgotten_by: obs.forgotten_by,
+      superseded_by: obs.superseded_by,
+      expires_at: obs.expires_at ?? null,
+      tags: JSON.stringify(obs.tags),
+      metadata: JSON.stringify(obs.metadata)
+    });
+    return obs;
+  }
+  getObservation(observationId) {
+    const row = this.db.prepare("SELECT * FROM observations WHERE observation_id = ?").get(observationId);
+    if (!row) return null;
+    return this.rowToObservation(row);
+  }
+  getObservations(entityId, includeForgotten = false) {
+    const where = includeForgotten ? "WHERE entity_id = ?" : "WHERE entity_id = ? AND forgotten_at IS NULL AND (expires_at IS NULL OR expires_at > datetime('now'))";
+    const rows = this.db.prepare(
+      `SELECT * FROM observations ${where} ORDER BY observed_at DESC`
+    ).all(entityId);
+    return rows.map((r) => this.rowToObservation(r));
+  }
+  forgetObservation(obsId, agentId) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    this.db.prepare("UPDATE observations SET forgotten_at = ?, forgotten_by = ? WHERE observation_id = ?").run(now, agentId, obsId);
+  }
+  supersede(oldObsId, newObs) {
+    this.db.prepare("UPDATE observations SET superseded_by = ? WHERE observation_id = ?").run(newObs.observation_id, oldObsId);
+    return this.addObservation(newObs);
+  }
+  // --- Relationships ---
+  addRelationship(rel) {
+    this.db.prepare(`
+      INSERT INTO relationships (relationship_id, from_entity_id, to_entity_id,
+        relationship_type, strength, source_receipt_id, created_at, forgotten_at, metadata)
+      VALUES (@relationship_id, @from_entity_id, @to_entity_id,
+        @relationship_type, @strength, @source_receipt_id, @created_at, @forgotten_at, @metadata)
+    `).run({
+      relationship_id: rel.relationship_id,
+      from_entity_id: rel.from_entity_id,
+      to_entity_id: rel.to_entity_id,
+      relationship_type: rel.relationship_type,
+      strength: rel.strength,
+      source_receipt_id: rel.source_receipt_id,
+      created_at: rel.created_at,
+      forgotten_at: rel.forgotten_at,
+      metadata: JSON.stringify(rel.metadata)
+    });
+    return rel;
+  }
+  getRelationships(entityId) {
+    const rows = this.db.prepare(
+      "SELECT * FROM relationships WHERE (from_entity_id = ? OR to_entity_id = ?) AND forgotten_at IS NULL ORDER BY created_at DESC"
+    ).all(entityId, entityId);
+    return rows.map((r) => this.rowToRelationship(r));
+  }
+  forgetRelationship(relId) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    this.db.prepare("UPDATE relationships SET forgotten_at = ? WHERE relationship_id = ?").run(now, relId);
+  }
+  // --- Search ---
+  search(query, filters) {
+    const limit = filters?.limit ?? 20;
+    let results;
+    try {
+      const ftsRows = this.db.prepare(`
+        SELECT o.*, observations_fts.rank
+        FROM observations_fts
+        JOIN observations o ON o.rowid = observations_fts.rowid
+        WHERE observations_fts MATCH ?
+          AND o.forgotten_at IS NULL
+          AND (o.expires_at IS NULL OR o.expires_at > datetime('now'))
+        ORDER BY rank
+        LIMIT ?
+      `).all(query, limit);
+      results = ftsRows.map((row) => {
+        const obs = this.rowToObservation(row);
+        const entity = this.getEntity(obs.entity_id);
+        return {
+          entity,
+          observation: obs,
+          rank: row.rank
+        };
+      }).filter((r) => r.entity !== null);
+    } catch {
+      const likeRows = this.db.prepare(`
+        SELECT * FROM observations
+        WHERE content LIKE ? AND forgotten_at IS NULL
+          AND (expires_at IS NULL OR expires_at > datetime('now'))
+        ORDER BY observed_at DESC
+        LIMIT ?
+      `).all(`%${query}%`, limit);
+      results = likeRows.map((row, idx) => {
+        const obs = this.rowToObservation(row);
+        const entity = this.getEntity(obs.entity_id);
+        return {
+          entity,
+          observation: obs,
+          rank: idx
+        };
+      }).filter((r) => r.entity !== null);
+    }
+    if (filters?.entity_type) {
+      results = results.filter((r) => r.entity.entity_type === filters.entity_type);
+    }
+    if (filters?.scope) {
+      results = results.filter((r) => r.entity.scope === filters.scope);
+    }
+    if (filters?.confidence_min) {
+      const minOrder = CONFIDENCE_ORDER[filters.confidence_min] ?? 0;
+      results = results.filter((r) => (CONFIDENCE_ORDER[r.observation.confidence] ?? 0) >= minOrder);
+    }
+    return results;
+  }
+  recall(query) {
+    if (query.query) {
+      const results = this.search(query.query, query);
+      const entityMap = /* @__PURE__ */ new Map();
+      const observations2 = [];
+      for (const r of results) {
+        entityMap.set(r.entity.entity_id, r.entity);
+        observations2.push(r.observation);
+      }
+      return {
+        entities: Array.from(entityMap.values()),
+        observations: observations2,
+        total: observations2.length
+      };
+    }
+    const entityResult = this.findEntities(query);
+    const observations = [];
+    for (const entity of entityResult.data) {
+      const obs = this.getObservations(entity.entity_id, query.include_forgotten);
+      observations.push(...obs);
+    }
+    return {
+      entities: entityResult.data,
+      observations,
+      total: observations.length
+    };
+  }
+  // --- Audit ---
+  getEntityHistory(entityId) {
+    const rows = this.db.prepare(
+      "SELECT * FROM observations WHERE entity_id = ? ORDER BY observed_at ASC"
+    ).all(entityId);
+    return rows.map((r) => this.rowToObservation(r));
+  }
+  getMemoryProvenance(observationId) {
+    const obs = this.getObservation(observationId);
+    if (!obs) return null;
+    const entity = this.getEntity(obs.entity_id);
+    if (!entity) return null;
+    return {
+      observation: obs,
+      entity,
+      receipt_id: obs.source_receipt_id,
+      chain: []
+    };
+  }
+  getMemoryStats(agentId, from, to) {
+    const entityConditions = [];
+    const obsConditions = [];
+    const params = [];
+    if (agentId) {
+      entityConditions.push("created_by_agent = ?");
+      obsConditions.push("source_agent_id = ?");
+      params.push(agentId);
+    }
+    const entityWhere = entityConditions.length > 0 ? `WHERE ${entityConditions.join(" AND ")}` : "";
+    const obsWhere = obsConditions.length > 0 ? `WHERE ${obsConditions.join(" AND ")}` : "";
+    const totalEntities = this.db.prepare(`SELECT COUNT(*) as cnt FROM entities ${entityWhere}`).get(...agentId ? [agentId] : []).cnt;
+    const totalObs = this.db.prepare(`SELECT COUNT(*) as cnt FROM observations ${obsWhere}`).get(...agentId ? [agentId] : []).cnt;
+    const totalRels = this.db.prepare("SELECT COUNT(*) as cnt FROM relationships").get().cnt;
+    const forgottenObs = this.db.prepare(`SELECT COUNT(*) as cnt FROM observations WHERE forgotten_at IS NOT NULL ${agentId ? "AND source_agent_id = ?" : ""}`).get(...agentId ? [agentId] : []).cnt;
+    const forgottenEntities = this.db.prepare(`SELECT COUNT(*) as cnt FROM entities WHERE forgotten_at IS NOT NULL ${agentId ? "AND created_by_agent = ?" : ""}`).get(...agentId ? [agentId] : []).cnt;
+    const typeRows = this.db.prepare("SELECT entity_type, COUNT(*) as cnt FROM entities GROUP BY entity_type").all();
+    const byType = {};
+    for (const r of typeRows) byType[r.entity_type] = r.cnt;
+    return {
+      total_entities: totalEntities,
+      total_observations: totalObs,
+      total_relationships: totalRels,
+      forgotten_observations: forgottenObs,
+      forgotten_entities: forgottenEntities,
+      by_entity_type: byType,
+      by_operation: {}
+    };
+  }
+  // --- Duplicate detection ---
+  findPossibleDuplicates(entityId) {
+    const entity = this.getEntity(entityId);
+    if (!entity) return [];
+    const nameTokens = entity.name.toLowerCase().split(/\s+/).filter((t) => t.length >= 2);
+    if (nameTokens.length === 0) return [];
+    const conditions = nameTokens.map(() => "(LOWER(name) LIKE ? OR LOWER(aliases) LIKE ?)").join(" OR ");
+    const params = [];
+    for (const token of nameTokens) {
+      params.push(`%${token}%`, `%${token}%`);
+    }
+    const rows = this.db.prepare(`
+      SELECT * FROM entities
+      WHERE entity_type = ?
+        AND entity_id != ?
+        AND forgotten_at IS NULL
+        AND merged_into IS NULL
+        AND (${conditions})
+    `).all(entity.entity_type, entityId, ...params);
+    return rows.map((r) => this.rowToEntity(r));
+  }
+  // --- Context helpers ---
+  getTopEntities(limit, scope) {
+    const scopeFilter = scope ? "AND e.scope = ?" : "";
+    const params = scope ? [scope, limit] : [limit];
+    const rows = this.db.prepare(`
+      SELECT e.*, COUNT(o.observation_id) as obs_count, MAX(o.observed_at) as latest
+      FROM entities e
+      LEFT JOIN observations o ON o.entity_id = e.entity_id AND o.forgotten_at IS NULL
+        AND (o.expires_at IS NULL OR o.expires_at > datetime('now'))
+      WHERE e.forgotten_at IS NULL AND e.merged_into IS NULL ${scopeFilter}
+      GROUP BY e.entity_id
+      ORDER BY obs_count DESC
+      LIMIT ?
+    `).all(...params);
+    return rows.map((r) => ({
+      ...this.rowToEntity(r),
+      observation_count: r.obs_count,
+      latest_observation: r.latest ?? ""
+    }));
+  }
+  getRecentObservations(limit, agentId) {
+    const agentFilter = agentId ? "AND source_agent_id = ?" : "";
+    const params = agentId ? [agentId, limit] : [limit];
+    const rows = this.db.prepare(`
+      SELECT * FROM observations
+      WHERE forgotten_at IS NULL
+        AND (expires_at IS NULL OR expires_at > datetime('now'))
+        ${agentFilter}
+      ORDER BY observed_at DESC
+      LIMIT ?
+    `).all(...params);
+    return rows.map((r) => this.rowToObservation(r));
+  }
+  getActiveRelationships(limit) {
+    const rows = this.db.prepare(
+      "SELECT * FROM relationships WHERE forgotten_at IS NULL ORDER BY created_at DESC LIMIT ?"
+    ).all(limit);
+    return rows.map((r) => this.rowToRelationship(r));
+  }
+  getPreferenceObservations(limit) {
+    const rows = this.db.prepare(`
+      SELECT o.* FROM observations o
+      JOIN entities e ON e.entity_id = o.entity_id
+      WHERE e.entity_type = 'preference'
+        AND o.forgotten_at IS NULL
+        AND (o.expires_at IS NULL OR o.expires_at > datetime('now'))
+      ORDER BY o.observed_at DESC
+      LIMIT ?
+    `).all(limit);
+    return rows.map((r) => this.rowToObservation(r));
+  }
+  getContextStats() {
+    const entities = this.db.prepare("SELECT COUNT(*) as cnt FROM entities WHERE forgotten_at IS NULL").get().cnt;
+    const observations = this.db.prepare("SELECT COUNT(*) as cnt FROM observations WHERE forgotten_at IS NULL AND (expires_at IS NULL OR expires_at > datetime('now'))").get().cnt;
+    const relationships = this.db.prepare("SELECT COUNT(*) as cnt FROM relationships WHERE forgotten_at IS NULL").get().cnt;
+    const agentRows = this.db.prepare("SELECT DISTINCT source_agent_id FROM observations WHERE forgotten_at IS NULL").all();
+    return {
+      total_entities: entities,
+      total_observations: observations,
+      total_relationships: relationships,
+      agents_contributing: agentRows.map((r) => r.source_agent_id)
+    };
+  }
+  // --- Cleanup ---
+  cleanupExpiredObservations() {
+    const result = this.db.prepare(`
+      UPDATE observations SET forgotten_at = datetime('now'), forgotten_by = 'system:cleanup'
+      WHERE expires_at IS NOT NULL AND expires_at <= datetime('now') AND forgotten_at IS NULL
+    `).run();
+    return result.changes;
+  }
+  // --- Row converters ---
+  rowToEntity(row) {
+    return {
+      entity_id: row.entity_id,
+      entity_type: row.entity_type,
+      name: row.name,
+      aliases: JSON.parse(row.aliases || "[]"),
+      scope: row.scope,
+      created_at: row.created_at,
+      created_by_agent: row.created_by_agent,
+      created_by_receipt: row.created_by_receipt,
+      forgotten_at: row.forgotten_at || null,
+      merged_into: row.merged_into || null,
+      attributes: JSON.parse(row.attributes || "{}"),
+      metadata: JSON.parse(row.metadata || "{}")
+    };
+  }
+  rowToObservation(row) {
+    return {
+      observation_id: row.observation_id,
+      entity_id: row.entity_id,
+      content: row.content,
+      confidence: row.confidence,
+      source_receipt_id: row.source_receipt_id,
+      source_agent_id: row.source_agent_id,
+      source_context: row.source_context || null,
+      observed_at: row.observed_at,
+      forgotten_at: row.forgotten_at || null,
+      forgotten_by: row.forgotten_by || null,
+      superseded_by: row.superseded_by || null,
+      expires_at: row.expires_at || null,
+      tags: JSON.parse(row.tags || "[]"),
+      metadata: JSON.parse(row.metadata || "{}")
+    };
+  }
+  rowToRelationship(row) {
+    return {
+      relationship_id: row.relationship_id,
+      from_entity_id: row.from_entity_id,
+      to_entity_id: row.to_entity_id,
+      relationship_type: row.relationship_type,
+      strength: row.strength,
+      source_receipt_id: row.source_receipt_id,
+      created_at: row.created_at,
+      forgotten_at: row.forgotten_at || null,
+      metadata: JSON.parse(row.metadata || "{}")
+    };
+  }
+};
+
 // src/engine/receipt-engine.ts
 import { nanoid } from "nanoid";
 import { ActionReceipt } from "@agent-receipts/schema";
@@ -1127,6 +1707,251 @@ var ReceiptEngine = class {
   }
 };
 
+// src/engine/memory-engine.ts
+import { nanoid as nanoid2 } from "nanoid";
+var MemoryEngine = class {
+  constructor(receiptEngine, memoryStore) {
+    this.receiptEngine = receiptEngine;
+    this.memoryStore = memoryStore;
+  }
+  async observe(params) {
+    const scope = params.scope ?? "agent";
+    const confidence = params.confidence ?? "medium";
+    let createdEntity = false;
+    let entity = this.memoryStore.findEntityByName(params.entityName, params.entityType);
+    const receipt = await this.receiptEngine.create({
+      action: "memory.observe",
+      receipt_type: "memory",
+      input_hash: hashData({ entityName: params.entityName, content: params.content }),
+      status: "completed",
+      metadata: {
+        memory: {
+          memory_operation: "observe",
+          entity_id: entity?.entity_id ?? null,
+          observation_id: null,
+          // Will be set below
+          relationship_id: null,
+          scope,
+          query: null,
+          results_count: null,
+          confidence
+        }
+      }
+    });
+    if (!entity) {
+      entity = this.memoryStore.createEntity({
+        entity_id: `ent_${nanoid2(12)}`,
+        entity_type: params.entityType,
+        name: params.entityName,
+        aliases: [],
+        scope,
+        created_at: (/* @__PURE__ */ new Date()).toISOString(),
+        created_by_agent: params.agentId,
+        created_by_receipt: receipt.receipt_id,
+        forgotten_at: null,
+        merged_into: null,
+        attributes: {},
+        metadata: {}
+      });
+      createdEntity = true;
+    }
+    const observation = this.memoryStore.addObservation({
+      observation_id: `obs_${nanoid2(12)}`,
+      entity_id: entity.entity_id,
+      content: params.content,
+      confidence,
+      source_receipt_id: receipt.receipt_id,
+      source_agent_id: params.agentId,
+      source_context: params.context ?? null,
+      observed_at: (/* @__PURE__ */ new Date()).toISOString(),
+      forgotten_at: null,
+      forgotten_by: null,
+      superseded_by: null,
+      expires_at: params.ttlSeconds ? new Date(Date.now() + params.ttlSeconds * 1e3).toISOString() : null,
+      tags: params.tags ?? [],
+      metadata: {}
+    });
+    return { entity, observation, receipt, created_entity: createdEntity };
+  }
+  async recall(params) {
+    const memoryQuery = {
+      query: params.query,
+      entity_type: params.entityType,
+      entity_id: params.entityId,
+      scope: params.scope,
+      limit: params.limit ?? 20,
+      include_forgotten: false,
+      page: 1
+    };
+    const result = this.memoryStore.recall(memoryQuery);
+    const receipt = await this.receiptEngine.create({
+      action: "memory.recall",
+      receipt_type: "memory",
+      input_hash: hashData({ query: params.query, entityType: params.entityType, entityId: params.entityId }),
+      output_hash: hashData({ entities: result.entities.length, observations: result.observations.length }),
+      status: "completed",
+      metadata: {
+        memory: {
+          memory_operation: "recall",
+          entity_id: params.entityId ?? null,
+          observation_id: null,
+          relationship_id: null,
+          scope: params.scope ?? "agent",
+          query: params.query ?? null,
+          results_count: result.total,
+          confidence: null
+        }
+      }
+    });
+    return {
+      entities: result.entities,
+      observations: result.observations,
+      receipt
+    };
+  }
+  async forget(params) {
+    const operation = params.entityId ? "memory.forget_entity" : "memory.forget";
+    if (params.entityId) {
+      this.memoryStore.forgetEntity(params.entityId, params.agentId);
+    } else if (params.observationId) {
+      this.memoryStore.forgetObservation(params.observationId, params.agentId);
+    } else {
+      throw new Error("Either entityId or observationId must be provided");
+    }
+    const receipt = await this.receiptEngine.create({
+      action: operation,
+      receipt_type: "memory",
+      input_hash: hashData({ entityId: params.entityId, observationId: params.observationId, reason: params.reason }),
+      status: "completed",
+      metadata: {
+        memory: {
+          memory_operation: params.entityId ? "forget_entity" : "forget",
+          entity_id: params.entityId ?? null,
+          observation_id: params.observationId ?? null,
+          relationship_id: null,
+          scope: "agent",
+          query: null,
+          results_count: null,
+          confidence: null
+        },
+        reason: params.reason
+      }
+    });
+    return { receipt };
+  }
+  async relate(params) {
+    const receipt = await this.receiptEngine.create({
+      action: "memory.relate",
+      receipt_type: "memory",
+      input_hash: hashData({ from: params.fromEntityId, to: params.toEntityId, type: params.relationshipType }),
+      status: "completed",
+      metadata: {
+        memory: {
+          memory_operation: "observe",
+          entity_id: params.fromEntityId,
+          observation_id: null,
+          relationship_id: null,
+          scope: "agent",
+          query: null,
+          results_count: null,
+          confidence: params.strength ?? "medium"
+        }
+      }
+    });
+    const relationship = this.memoryStore.addRelationship({
+      relationship_id: `rel_${nanoid2(12)}`,
+      from_entity_id: params.fromEntityId,
+      to_entity_id: params.toEntityId,
+      relationship_type: params.relationshipType,
+      strength: params.strength ?? "medium",
+      source_receipt_id: receipt.receipt_id,
+      created_at: (/* @__PURE__ */ new Date()).toISOString(),
+      forgotten_at: null,
+      metadata: params.context ? { context: params.context } : {}
+    });
+    return { relationship, receipt };
+  }
+  async merge(params) {
+    const mergedEntity = this.memoryStore.mergeEntities(params.sourceEntityId, params.targetEntityId);
+    const receipt = await this.receiptEngine.create({
+      action: "memory.merge",
+      receipt_type: "memory",
+      input_hash: hashData({ source: params.sourceEntityId, target: params.targetEntityId }),
+      output_hash: hashData(mergedEntity),
+      status: "completed",
+      metadata: {
+        memory: {
+          memory_operation: "merge",
+          entity_id: params.targetEntityId,
+          observation_id: null,
+          relationship_id: null,
+          scope: mergedEntity.scope,
+          query: null,
+          results_count: null,
+          confidence: null
+        }
+      }
+    });
+    return { mergedEntity, receipt };
+  }
+  provenance(observationId) {
+    return this.memoryStore.getMemoryProvenance(observationId);
+  }
+  entityTimeline(entityId) {
+    const observations = this.memoryStore.getEntityHistory(entityId);
+    const relationships = this.memoryStore.getRelationships(entityId);
+    const entries = [];
+    for (const obs of observations) {
+      entries.push({
+        type: obs.forgotten_at ? "forget" : "observation",
+        timestamp: obs.observed_at,
+        data: obs
+      });
+    }
+    for (const rel of relationships) {
+      entries.push({
+        type: "relationship",
+        timestamp: rel.created_at,
+        data: rel
+      });
+    }
+    entries.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    return entries;
+  }
+  memoryAudit(params) {
+    return this.memoryStore.getMemoryStats(params.agentId, params.from, params.to);
+  }
+  async getContext(params) {
+    const maxEntities = Math.min(params.maxEntities ?? 10, 50);
+    const maxObservations = Math.min(params.maxObservations ?? 20, 100);
+    const entities = this.memoryStore.getTopEntities(maxEntities, params.scope);
+    const recent_observations = this.memoryStore.getRecentObservations(maxObservations, params.agentId);
+    const relationships = this.memoryStore.getActiveRelationships(50);
+    const preferences = this.memoryStore.getPreferenceObservations(20);
+    const stats = this.memoryStore.getContextStats();
+    const receipt = await this.receiptEngine.create({
+      action: "memory.context",
+      receipt_type: "memory",
+      input_hash: hashData({ scope: params.scope, maxEntities, maxObservations }),
+      output_hash: hashData({ entities: entities.length, observations: recent_observations.length }),
+      status: "completed",
+      metadata: {
+        memory: {
+          memory_operation: "recall",
+          entity_id: null,
+          observation_id: null,
+          relationship_id: null,
+          scope: params.scope ?? "agent",
+          query: null,
+          results_count: entities.length + recent_observations.length,
+          confidence: null
+        }
+      }
+    });
+    return { entities, recent_observations, relationships, preferences, stats, receipt };
+  }
+};
+
 // src/engine/invoice-formatters.ts
 function formatInvoiceJSON(invoice, includeReceipts = false) {
   if (!includeReceipts) {
@@ -1722,6 +2547,8 @@ export {
   ConfigManager,
   ReceiptStore as JsonReceiptStore,
   KeyManager,
+  MemoryEngine,
+  MemoryStore,
   ReceiptEngine,
   SqliteReceiptStore as ReceiptStore,
   SqliteReceiptStore,