memory_import_bundle

Instructions

Implementation Reference

• packages/mcp-server/src/engine/memory-engine.ts:490-564 (handler)

  Core importBundle method on MemoryEngine — verifies bundle checksum, imports entities/observations/relationships (skipping existing if configured), records the operation as a signed receipt.

  async importBundle(bundle: MemoryBundle, params?: {
    skipExisting?: boolean
  }): Promise<ImportBundleResult> {
    const { skipExisting = true } = params ?? {}
  
    // Verify checksum
    const checksumPayload = JSON.stringify({
      entities: [...bundle.entities].sort((a, b) => a.entity_id.localeCompare(b.entity_id)),
      observations: [...bundle.observations].sort((a, b) => a.observation_id.localeCompare(b.observation_id)),
      relationships: [...bundle.relationships].sort((a, b) => a.relationship_id.localeCompare(b.relationship_id)),
    })
    const computedChecksum = hashData(checksumPayload)
    if (computedChecksum !== bundle.checksum) {
      throw new Error('Bundle checksum mismatch — data may have been tampered with')
    }
  
    const imported = { entities: 0, observations: 0, relationships: 0 }
    const skipped = { entities: 0, observations: 0, relationships: 0 }
  
    for (const entity of bundle.entities) {
      const existing = this.memoryStore.getEntity(entity.entity_id)
      if (existing && skipExisting) {
        skipped.entities++
        continue
      }
      if (!existing) {
        this.memoryStore.createEntity(entity)
        imported.entities++
      }
    }
  
    for (const obs of bundle.observations) {
      const existing = this.memoryStore.getObservation(obs.observation_id)
      if (existing && skipExisting) {
        skipped.observations++
        continue
      }
      if (!existing) {
        this.memoryStore.addObservation(obs)
        imported.observations++
      }
    }
  
    for (const rel of bundle.relationships) {
      try {
        this.memoryStore.addRelationship(rel)
        imported.relationships++
      } catch {
        skipped.relationships++
      }
    }
  
    const receipt = await this.receiptEngine.create({
      action: 'memory.import_bundle',
      receipt_type: 'memory',
      input_hash: hashData({ bundle_id: bundle.bundle_id }),
      output_hash: hashData(imported),
      status: 'completed',
      metadata: {
        memory: {
          memory_operation: 'create',
          entity_id: null,
          observation_id: null,
          relationship_id: null,
          scope: 'user',
          query: null,
          results_count: imported.entities + imported.observations + imported.relationships,
          confidence: null,
        },
        bundle_id: bundle.bundle_id,
      },
    })
  
    return { imported, skipped, receipt }
  }

• packages/schema/src/memory.ts:121-126 (schema)

  Zod schema for MemoryBundle — the bundle format validated on import (bundle_id, checksum, entities, observations, relationships, etc.)

  })
  export type MemoryQuery = z.infer<typeof MemoryQuery>
  
  // --- Bundle Types ---
  
  export const MemoryBundle = z.object({

• packages/mcp-server/src/engine/memory-engine.ts:117-121 (schema)

  ImportBundleResult interface — shape of the result returned by importBundle.

  export interface ImportBundleResult {
    imported: { entities: number; observations: number; relationships: number }
    skipped: { entities: number; observations: number; relationships: number }
    receipt: ActionReceipt
  }

• packages/mcp-server/src/tools/memory-import-bundle.ts:1-31 (handler)

  MCP tool registration — defines Zod input schema (bundle, skip_existing), calls memoryEngine.importBundle, returns JSON result.

  import { z } from 'zod'
  import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
  import type { MemoryEngine } from '../engine/memory-engine.js'
  
  export function registerMemoryImportBundle(server: McpServer, memoryEngine: MemoryEngine): void {
    server.tool(
      'memory_import_bundle',
      'Import a memory bundle from another Agent Receipts instance. Verifies checksums before importing. Skips memories that already exist locally. The import operation itself is recorded as a signed receipt.',
      {
        bundle: z.record(z.unknown()).describe('The memory bundle JSON object to import'),
        skip_existing: z.boolean().optional().describe('Skip entities/observations that already exist (default: true)'),
      },
      async (params) => {
        const result = await memoryEngine.importBundle(
          params.bundle as Parameters<typeof memoryEngine.importBundle>[0],
          { skipExisting: params.skip_existing },
        )
  
        return {
          content: [{
            type: 'text' as const,
            text: JSON.stringify({
              imported: result.imported,
              skipped: result.skipped,
              receipt_id: result.receipt.receipt_id,
            }, null, 2),
          }],
        }
      },
    )
  }

• packages/mcp-server/src/tools/index.ts:28-65 (registration)

  Import and registration of the memory_import_bundle tool in registerAllTools.

  import { registerMemoryImportBundle } from './memory-import-bundle.js'
  
  export function registerAllTools(
    server: McpServer,
    engine: ReceiptEngine,
    memoryEngine?: MemoryEngine,
    memoryStore?: MemoryStore,
    agentId?: string,
  ): void {
    registerCreateReceipt(server, engine)
    registerCompleteReceipt(server, engine)
    registerTrackAction(server, engine)
    registerVerifyReceipt(server, engine)
    registerGetReceipt(server, engine)
    registerListReceipts(server, engine)
    registerGetChain(server, engine)
    registerGetPublicKey(server, engine)
    registerJudgeReceipt(server, engine)
    registerCompleteJudgment(server, engine)
    registerGetJudgments(server, engine)
    registerCleanup(server, engine, memoryStore)
    registerGenerateInvoice(server, engine)
    registerGetStarted(server, engine)
  
    // Memory tools
    if (memoryEngine && memoryStore && agentId) {
      registerMemoryObserve(server, memoryEngine, agentId, memoryStore)
      registerMemoryRecall(server, memoryEngine, agentId)
      registerMemoryForget(server, memoryEngine, agentId)
      registerMemoryEntities(server, memoryStore)
      registerMemoryRelate(server, memoryEngine, agentId)
      registerMemoryProvenance(server, memoryEngine)
      registerMemoryAudit(server, memoryEngine)
      registerMemoryContext(server, memoryEngine)
      registerMemoryExportBundle(server, memoryEngine)
      registerMemoryImportBundle(server, memoryEngine)
    }
  }