{
  "id": "page:docs-supermemory-research-integration-plan",
  "_kind": "Page",
  "_file": "wiki/docs/supermemory-research/integration-plan.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/supermemory-research/integration-plan.md",
    "sourceKind": "repo-docs",
    "title": "Supermemory Integration Plan",
    "displayName": "Supermemory Integration Plan",
    "slug": "docs/supermemory-research/integration-plan",
    "articlePath": "wiki/docs/supermemory-research/integration-plan.md",
    "article": "\n# Supermemory Integration Plan\n\nConcrete next steps for integrating Supermemory as a memory backend for the\nbabysitter/genty agentic stack.\n\n## Phase 0: Prerequisites\n\n### 0.1 Obtain API Access\n\n- Sign up at https://console.supermemory.ai\n- Create API key (prefixed `sm_`)\n- Store in 1Password and configure as `SUPERMEMORY_API_KEY` env var\n\n### 0.2 Install SMFS Binary\n\n```bash\ncurl -fsSL https://smfs.ai/install | bash\nsmfs login  # one-time credential storage\n```\n\n### 0.3 Add SDK Dependencies\n\n```bash\n# In packages/genty/platform\nnpm install supermemory\n\n# For serverless runtime (if needed)\nnpm install @supermemory/bash\n```\n\n## Phase 1: SMFS Mount Adapter (L5 Runtime Integration)\n\n### Goal\n\nCreate a memory adapter that mounts a Supermemory container at run start and\nunmounts at run end, giving agents transparent semantic memory via filesystem.\n\n### 1.1 Create Mount Adapter\n\nFile: `packages/genty/platform/src/session/supermemoryMount.ts`\n\n```typescript\ninterface SupermemoryMountConfig {\n  apiKey: string;\n  containerTag: string;\n  memoryPaths: string[];  // e.g., [\"/decisions/\", \"/findings/\", \"/patterns/\"]\n  syncInterval?: number;  // seconds, default 30\n}\n\ninterface SupermemoryMount {\n  mountPath: string;\n  unmount(): Promise<void>;\n}\n\nexport async function mountSupermemory(config: SupermemoryMountConfig): Promise<SupermemoryMount>;\nexport async function unmountSupermemory(mount: SupermemoryMount): Promise<void>;\n```\n\nImplementation spawns `smfs mount` as a child process with the configured\ncontainer tag and memory paths. Returns the mount path for use as the agent's\nworking directory or a symlinked subdirectory.\n\n### 1.2 Create Virtual Bash Adapter\n\nFile: `packages/genty/platform/src/session/supermemoryBash.ts`\n\nFor serverless environments where SMFS mount is unavailable. Wraps\n`@supermemory/bash` as a tool provider in the genty runtime.\n\n```typescript\nimport { createBash } from \"@supermemory/bash\";\n\nexport async function createSupermemoryBashTool(config: {\n  apiKey: string;\n  containerTag: string;\n}): Promise<AgentTool>;\n```\n\n### 1.3 Wire into Session Lifecycle\n\nModify the session lifecycle in genty-platform to:\n1. Check for `SUPERMEMORY_API_KEY` env var\n2. If present, mount SMFS container at session start\n3. Configure memory paths based on process definition\n4. Unmount and drain writes at session end\n\n## Phase 2: Profile-Driven Context Injection\n\n### Goal\n\nUse Supermemory's profile API to inject cross-run context into the agent's\nsystem prompt at run start.\n\n### 2.1 Create Profile Fetcher\n\nFile: `packages/genty/platform/src/session/supermemoryProfile.ts`\n\n```typescript\nimport { Supermemory } from \"supermemory\";\n\nexport async function fetchSupermemoryProfile(config: {\n  apiKey: string;\n  containerTag: string;\n  query: string;\n}): Promise<{ staticProfile: string; dynamicProfile: string; memories: string[] }>;\n```\n\n### 2.2 Inject into System Prompt\n\nAt run start, if Supermemory is configured:\n1. Call `client.profile()` with the run's user/project scope\n2. Append the static profile and relevant memories to the system prompt\n3. This gives the agent immediate context about the user/project\n\n### 2.3 Persist Run Outcomes\n\nAt run end:\n1. Extract key decisions, findings, and outcomes from the run journal\n2. Call `client.add()` for each significant item with metadata:\n   - `containerTag`: user/project scope\n   - `metadata.runId`: current run ID\n   - `metadata.processId`: process definition ID\n   - `metadata.outcome`: success/failure/partial\n\n## Phase 3: Knowledge Fabric Atlas Node\n\n### Goal\n\nRegister Supermemory as a knowledge fabric implementation in the atlas graph\nand configure it as the default memory provider for supported deployments.\n\n### 3.1 Atlas Graph (Done)\n\nThree YAML nodes created in `packages/atlas/graph/agent-stack/supermemory/`:\n- `supermemory-overview.yaml` -- product-level overview\n- `supermemory-smfs.yaml` -- SMFS filesystem interface\n- `supermemory-api.yaml` -- REST API and MCP server\n\n### 3.2 Update Memory Service Fabrics\n\nAdd Supermemory entry to `packages/atlas/graph/agent-stack/knowledge-fabric-impls/memory-service-fabrics.yaml`\nalongside existing Mem0 and Zep entries.\n\n## Phase 4: MemoryBench Evaluation\n\n### Goal\n\nRun MemoryBench to quantitatively compare our current memory pipeline against\nSupermemory.\n\n### 4.1 Install MemoryBench\n\n```bash\ngit clone https://github.com/supermemoryai/supermemory\ncd supermemory/apps/memorybench\nbun install\n```\n\n### 4.2 Create Custom Evaluation\n\nWrite a MemoryBench evaluation that tests:\n- Cross-run memory recall (does the agent remember decisions from 5 runs ago?)\n- Contradiction resolution (does the agent use the latest information?)\n- User preference retrieval (does the agent respect known preferences?)\n- Temporal reasoning (does the agent understand time-ordered events?)\n\n### 4.3 Run Comparison\n\nCompare three configurations:\n1. Current genty memory (memoryExtraction + consolidation)\n2. Supermemory via REST API\n3. Supermemory via SMFS\n\nMeasure: accuracy, latency, token usage, cost per query.\n\n## Phase 5: Production Rollout\n\n### 5.1 Configuration\n\nAdd to process definition schema:\n```yaml\nmemory:\n  provider: supermemory | local | none\n  containerTag: \"${userId}-${projectId}\"\n  memoryPaths:\n    - /decisions/\n    - /findings/\n    - /patterns/\n  profileQuery: \"relevant context for ${processDescription}\"\n```\n\n### 5.2 Graceful Degradation\n\nIf `SUPERMEMORY_API_KEY` is not set or Supermemory is unreachable:\n- Log a warning\n- Continue with local memory pipeline (memoryExtraction + consolidation)\n- Do NOT add a silent fallback -- surface the configuration issue clearly\n\n### 5.3 Kradle Integration\n\nFor Kradle-hosted runs:\n- Pass `SUPERMEMORY_API_KEY` as a secret\n- Use `@supermemory/bash` virtual tool (no FUSE in containers without SYS_ADMIN)\n- Or configure Docker with `--device /dev/fuse --cap-add SYS_ADMIN` for SMFS mount\n\n## Timeline Estimate\n\n| Phase | Scope                            | Effort    |\n|-------|----------------------------------|-----------|\n| 0     | Prerequisites                    | 1 hour    |\n| 1     | SMFS mount + virtual bash adapter| 2-3 days  |\n| 2     | Profile injection + persistence  | 1-2 days  |\n| 3     | Atlas graph nodes                | Done      |\n| 4     | MemoryBench evaluation           | 2-3 days  |\n| 5     | Production rollout               | 3-5 days  |\n\nTotal: ~2-3 weeks for full integration.\n\n## Open Questions\n\n1. **Pricing model**: What is Supermemory's cost per query at our expected volume?\n   Need to evaluate before committing to production use.\n\n2. **Data residency**: Where does Supermemory store data? Relevant for enterprise\n   customers with data sovereignty requirements.\n\n3. **Self-hosting**: Can we run Supermemory's memory engine locally? The repo is\n   MIT-licensed, but the cloud infrastructure (Cloudflare Workers, KV, etc.)\n   may not be self-hostable.\n\n4. **Container isolation**: How are containers isolated between users? Need to\n   verify that one user's memories cannot leak to another.\n\n5. **Rate limits**: What are the API rate limits? Babysitter runs can generate\n   many memory operations in rapid succession.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-supermemory-research",
      "to": "page:docs-supermemory-research-integration-plan",
      "kind": "contains_page"
    }
  ]
}