{
  "id": "page:docs-supermemory-research-layer-analysis",
  "_kind": "Page",
  "_file": "wiki/docs/supermemory-research/layer-analysis.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/supermemory-research/layer-analysis.md",
    "sourceKind": "repo-docs",
    "title": "Supermemory Layer Analysis",
    "displayName": "Supermemory Layer Analysis",
    "slug": "docs/supermemory-research/layer-analysis",
    "articlePath": "wiki/docs/supermemory-research/layer-analysis.md",
    "article": "\n# Supermemory Layer Analysis\n\nDeep analysis of Supermemory through the agentic layer lens, mapping its capabilities\nto our L1-L14 atlas layer model and comparing with existing genty memory infrastructure.\n\n## 1. SMFS Mapping to L4-L5 Layers\n\n### L4 -- Agent Core\n\nSMFS does not operate at L4 (agent core loop). It is not an agent runtime or\norchestration engine. However, it fundamentally shapes what tools an L4 agent has\navailable. When SMFS is mounted, the agent's tool surface changes:\n\n- `grep` becomes semantic search (no flags = semantic, flags = exact-match)\n- `cat profile.md` returns a live-synthesized user digest (not a stored file)\n- Standard `ls`, `cat`, `echo >` work against the knowledge graph as if it were a filesystem\n\nThis is a *tool-shaping* integration at L4: the agent uses the same tool calls\n(Bash/Read/Write) but the backing implementation routes through Supermemory's\nsemantic index transparently.\n\n### L5 -- Agent Runtime\n\nSMFS maps most naturally to L5 (Agent Runtime), specifically the session persistence\nand memory extraction subsystem:\n\n| L5 Concern              | Our Implementation                           | SMFS Equivalent                              |\n|--------------------------|----------------------------------------------|----------------------------------------------|\n| Session persistence      | `crossRunState.ts` (JSON key-value store)    | Container as mounted directory               |\n| Memory extraction        | `memoryExtraction.ts` (LLM-extracted facts)  | Automatic memory from written files           |\n| Memory consolidation     | `memoryConsolidation.ts` (Jaccard dedup)     | Knowledge graph with Update/Extend/Derive     |\n| Memory retrieval         | `queryMemories()` (category/tag filter)      | `grep` (semantic) + `cat profile.md` (digest) |\n| Cross-session state      | `shared-state.json` file                     | Persistent container with bidirectional sync   |\n\n**Key difference**: Our L5 memory is *pull-based* -- we explicitly call\n`extractMemoriesFromSession()` and `persistMemories()` at session boundaries.\nSMFS is *ambient* -- writes to the mounted directory are automatically indexed\nand become searchable. The agent does not need to know it is using a memory system.\n\n### L5 Runtime Integration Points\n\nSMFS's virtual Bash tool (`@supermemory/bash`) is directly pluggable into our\nruntime as an additional tool provider. The `createBash()` factory returns a tool\nthat can be injected alongside our existing tool surface.\n\n```typescript\n// Hypothetical genty integration\nconst { bash } = await createBash({\n  apiKey: process.env.SUPERMEMORY_API_KEY,\n  containerTag: `run-${runId}-user-${userId}`,\n});\n// bash.exec() becomes available as a tool alongside our existing tools\n```\n\n## 2. Memory API Comparison\n\n### Our Memory Pipeline\n\n```\nSession Messages -> extractMemoriesFromSession() -> MemoryEntry[]\n                                                          |\n                                                    persistMemories()\n                                                          |\n                                                  long-term-memory.json\n                                                          |\n                                                  queryMemories() (filter by category/tags)\n                                                          |\n                                                  consolidateMemories() (Jaccard dedup, prune)\n```\n\n**Characteristics:**\n- Extraction: LLM-assisted, produces `MemoryEntry` objects with category/confidence/tags\n- Storage: Local JSON file (`long-term-memory.json`)\n- Retrieval: Filter-based (category, tags, limit) -- no semantic search\n- Deduplication: Jaccard word-set similarity (threshold 0.4)\n- Limits: 500 entries max (extraction), 200 after consolidation\n- No knowledge graph, no relationship tracking between memories\n\n### Supermemory Memory Pipeline\n\n```\nContent (text/files/URLs) -> POST /v3/documents\n                                    |\n                          Queued -> Extracting -> Chunking -> Embedding -> Indexing -> Done\n                                    |\n                          Knowledge Graph (Update / Extend / Derive relationships)\n                                    |\n                          Three retrieval paths:\n                            1. Memory API (evolved user facts)\n                            2. User Profiles (static + dynamic digest)\n                            3. RAG Search (semantic + metadata filtering)\n```\n\n**Characteristics:**\n- Extraction: Automatic from any content type (text, PDF, images, video)\n- Storage: Cloud knowledge graph with vector embeddings\n- Retrieval: Semantic search, hybrid search, profile synthesis\n- Deduplication: Knowledge graph relationships (Update supersedes, Extend enriches, Derive infers)\n- Limits: Scales to billions of data points\n- Active contradiction resolution and temporal decay\n\n### Gap Analysis\n\n| Capability                       | Genty (Current)          | Supermemory              | Gap                                          |\n|----------------------------------|--------------------------|--------------------------|----------------------------------------------|\n| Semantic search                  | None                     | Core feature             | Critical gap -- our retrieval is filter-only  |\n| Contradiction resolution         | None                     | Automatic via Updates    | Significant gap                              |\n| Temporal decay / forgetting      | Manual prune by count    | Brain-inspired decay     | Moderate gap                                 |\n| Knowledge graph relationships    | None                     | Update/Extend/Derive    | Significant gap                              |\n| Multi-modal extraction           | None                     | PDF, image, video, code  | Large gap                                    |\n| Retrieval latency                | ~instant (local JSON)    | ~50ms (cloud API)        | Our advantage for simple cases               |\n| Offline operation                | Full (local files)       | Requires network         | Our advantage                                |\n| User profiles                    | None                     | Static + dynamic         | Moderate gap                                 |\n| Cross-run state                  | Key-value store          | Container persistence    | Parity (different models)                    |\n\n## 3. MCP Integration Comparison\n\n### Our MCP Client\n\nOur stack uses MCP for tool and resource integration from external servers. The MCP\nclient in the genty platform connects to MCP servers configured in `.mcp.json` or\nequivalent, providing tools to the agent runtime.\n\n### Supermemory MCP Server\n\nSupermemory exposes itself as an MCP server with four tools:\n- `addMemory` -- save information\n- `search` -- retrieve memories and profiles\n- `getProjects` -- list projects\n- `whoAmI` -- user identity\n\n**Integration model**: Supermemory's MCP server is a *provider*, our MCP client is\na *consumer*. The integration is straightforward -- add Supermemory's MCP endpoint\nto our MCP client configuration.\n\n**However**, the SMFS approach may be superior for our use case. Instead of adding\nMCP tools that the agent must learn to call, SMFS makes memory transparent through\nthe filesystem. The agent writes files and searches with grep -- operations it\nalready knows how to do. This avoids adding cognitive load to the agent prompt.\n\n### Recommendation\n\nFor genty integration, prefer SMFS (filesystem mount or virtual bash tool) over\nthe raw MCP server. The MCP server is better suited for interactive IDE clients\n(Cursor, VS Code) where memory persistence across human chat sessions is the goal.\nFor orchestrated agent runs, SMFS provides the same memory without requiring the\nagent to learn new tools.\n\n## 4. Unique Capabilities\n\n### Semantic Memory File System (SMFS)\n\nThe most distinctive feature. No other memory provider collapses four components\n(vector DB, memory service, profile store, SDK) into a single filesystem mount.\nThis is architecturally novel and maps perfectly to agents that already interact\nwith filesystems.\n\n**Benchmark results** (xAFS evaluation):\n- 81% accuracy at 10,000 files vs 69% for baseline\n- 55% cheaper ($946 vs $2,103)\n- 53.8% fewer tokens\n- For Claude: -66% tokens, -60% tool calls\n\n### Knowledge Graph Relationships\n\nThree relationship types (Update, Extend, Derive) provide automatic knowledge\nevolution that no other memory system offers at this level:\n- **Update**: New info contradicts old -- system tracks which is current\n- **Extend**: New info enriches without replacing\n- **Derive**: System infers connections not explicitly stated\n\n### Brain-Inspired Decay\n\nMemory importance decays over time unless reinforced by access, mimicking\nbiological forgetting curves. This prevents memory bloat without manual pruning.\n\n### User Profile Synthesis\n\n`cat profile.md` returns a regenerated-on-read digest of all memories for a\ncontainer. This is not stored -- it is synthesized each time, ensuring it always\nreflects the latest state. No equivalent exists in our stack.\n\n## 5. Integration Opportunities\n\n### Tier 1: Drop-In SMFS Mount for Babysitter Runs\n\nMount a Supermemory container per user/project at run start. Agent writes to\nmemory paths during the run; memories persist across runs automatically.\n\n```bash\nsmfs mount \"babysitter-${userId}-${projectId}\" \\\n  --memory-paths \"/decisions/,/findings/,/patterns/\"\n```\n\nThis replaces `memoryExtraction.ts` + `memoryConsolidation.ts` for cross-run\nknowledge persistence while adding semantic search, contradiction resolution,\nand knowledge graph relationships for free.\n\n### Tier 2: Virtual Bash Tool for Serverless Runs\n\nFor cloud-hosted babysitter runs (Kradle), use `@supermemory/bash` as a virtual\nfilesystem tool. Same semantics as mount but works in Lambda/Workers/containers.\n\n### Tier 3: Profile-Driven Context Injection\n\nUse `client.profile()` at run start to inject relevant cross-run context into\nthe system prompt. Replaces manual `queryMemories()` calls with a single API\ncall that returns a curated, synthesized user profile.\n\n### Tier 4: Hybrid -- SMFS for Agent, API for Orchestrator\n\nThe orchestrator (genty-platform) uses the REST API for structured memory\noperations (add with metadata, search with filters). The agent (within the run)\nuses SMFS for transparent file-based memory. Both write to the same container\nvia shared `containerTag`.\n\n### Non-Opportunity: Replacing crossRunState.ts\n\n`crossRunState.ts` is a simple key-value store for structured orchestration\nstate (last checkpoint, current phase, etc.). This is not a memory problem --\nit is a state problem. Supermemory is not the right tool for this.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-supermemory-research",
      "to": "page:docs-supermemory-research-layer-analysis",
      "kind": "contains_page"
    }
  ]
}