# supermemoryai/claude-supermemory architecture

> Architecture diagram of the GitHub repository supermemoryai/claude-supermemory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supermemoryai/claude-supermemory
- Repository: https://github.com/supermemoryai/claude-supermemory

## Overview

Claude-Supermemory is a Claude Code plugin that supplies persistent, repository-scoped memory through Supermemory. The main workflow starts a session by loading profile context, conditionally recalls relevant memories before prompts, and captures conversation content when a session ends. Users can also explicitly search or save memories and run project configuration, indexing, logout, and session commands. The graph includes configuration/authentication and statusline state as supporting layers. Some subsystem links are based on README statements or SOURCE INDEX references; unsampled implementations are not treated as inspected.

Main entry points: [`plugin/hooks/session-start.js`](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/session-start.js) (Session Context), [`plugin/hooks/capture.js`](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/capture.js) (Auto Capture), [`plugin/hooks/recall-directive.js`](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/recall-directive.js) (Reasoned Recall), [`plugin/hooks/lib/api.js`](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/api.js) (Memory API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_session["Session Memory"]
  node_session_start["Session Context<br/>[session-start.js]"]
  node_recall["Reasoned Recall"]
  node_capture["Auto Capture<br/>[capture.js]"]
  node_transcript["Transcript Processing<br/>[transcript.js]"]
  node_api["Memory API Client<br/>[api.js]"]
end

subgraph group_configuration["Configuration"]
  node_auth["Browser Authentication<br/>[auth.js]"]
  node_settings["Settings and Credentials<br/>[settings.js]"]
  node_project_config["Project Configuration<br/>[project-config.js]"]
  node_container["Repository Container<br/>[container-tag.js]"]
end

subgraph group_integration["Claude Integration"]
  node_commands["Plugin Commands<br/>[index.md]"]
  node_agent["Context Gatherer"]
  node_mcp["Memory Tool Proxy<br/>[mcp-proxy.js]"]
  node_recall_approve["Recall Approval<br/>[recall-approve.js]"]
end

subgraph group_support["Status and State"]
  node_statusline["Statusline Renderer<br/>[statusline.js]"]
  node_state[("Session Status State")]
  node_last_session[("Last Session Link<br/>[last-session.js]")]
end

node_user(("Developer"))
node_claude(("Claude Code"))
node_supermemory[("Supermemory Service")]

node_user -->|"prompts"| node_claude
node_claude -->|"starts session"| node_session_start
node_session_start -->|"loads settings"| node_settings
node_session_start -->|"loads project config"| node_project_config
node_session_start -->|"selects container"| node_container
node_session_start -->|"authenticates if needed"| node_auth
node_session_start -->|"fetches profile"| node_api
node_api -->|"requests profile"| node_supermemory
node_session_start -->|"injects context"| node_claude
node_claude -->|"submits prompt"| node_recall
node_recall -->|"reads recall config"| node_settings
node_recall -->|"loads project config"| node_project_config
node_recall -->|"selects container"| node_container
node_recall -->|"searches profile"| node_api
node_recall -->|"injects matches"| node_claude
node_claude -->|"ends session"| node_capture
node_capture -->|"processes transcript"| node_transcript
node_capture -->|"reads capture settings"| node_settings
node_capture -->|"selects container"| node_container
node_capture -->|"saves memories"| node_api
node_api -->|"writes documents"| node_supermemory
node_user -->|"runs commands"| node_commands
node_commands -.->|"configures project"| node_project_config
node_user -->|"requests search or save"| node_mcp
node_mcp -->|"uses memory API"| node_api
node_user -.->|"requests context gathering"| node_agent
node_recall_approve -->|"updates recall state"| node_state
node_session_start -->|"writes context state"| node_state
node_capture -->|"writes capture state"| node_state
node_statusline -.->|"reads session state"| node_state
node_capture -->|"stores session link"| node_last_session
node_session_start -->|"installs statusline"| node_statusline
node_settings -->|"loads credentials"| node_auth

click node_session_start "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/session-start.js"
click node_recall "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/recall-directive.js"
click node_capture "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/capture.js"
click node_transcript "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/transcript.js"
click node_api "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/api.js"
click node_auth "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/auth.js"
click node_settings "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/settings.js"
click node_project_config "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/project-config.js"
click node_container "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/container-tag.js"
click node_commands "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/commands/index.md"
click node_agent "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/agents/context-gatherer.md"
click node_mcp "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/mcp-proxy.js"
click node_recall_approve "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/recall-approve.js"
click node_statusline "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/statusline.js"
click node_state "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/statusline-state.js"
click node_last_session "https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/last-session.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_session_start,node_recall,node_capture,node_transcript,node_api toneBlue
class node_auth,node_settings,node_project_config,node_container,node_supermemory toneAmber
class node_commands,node_agent,node_mcp,node_recall_approve toneMint
class node_statusline,node_state,node_last_session toneRose
class node_user,node_claude toneIndigo
```

## Components

### Session Memory

- [Session Context](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/session-start.js): `plugin/hooks/session-start.js`
- [Reasoned Recall](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/recall-directive.js): `plugin/hooks/recall-directive.js`
- [Auto Capture](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/capture.js): `plugin/hooks/capture.js`
- [Transcript Processing](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/transcript.js): `plugin/hooks/lib/transcript.js`
- [Memory API Client](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/api.js): `plugin/hooks/lib/api.js`

### Configuration

- [Browser Authentication](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/auth.js): `plugin/hooks/lib/auth.js`
- [Settings and Credentials](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/settings.js): `plugin/hooks/lib/settings.js`
- [Project Configuration](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/project-config.js): `plugin/hooks/lib/project-config.js`
- [Repository Container](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/container-tag.js): `plugin/hooks/lib/container-tag.js`

### Claude Integration

- [Plugin Commands](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/commands/index.md): `plugin/commands/index.md`
- [Context Gatherer](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/agents/context-gatherer.md): `plugin/agents/context-gatherer.md`
- [Memory Tool Proxy](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/mcp-proxy.js): `plugin/hooks/mcp-proxy.js`
- [Recall Approval](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/recall-approve.js): `plugin/hooks/recall-approve.js`

### Status and State

- [Statusline Renderer](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/statusline.js): `plugin/statusline.js`
- [Session Status State](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/statusline-state.js): `plugin/hooks/lib/statusline-state.js`
- [Last Session Link](https://github.com/supermemoryai/claude-supermemory/blob/main/plugin/hooks/lib/last-session.js): `plugin/hooks/lib/last-session.js`

### Other components

- **Developer**
- **Claude Code**
- **Supermemory Service**

## Connections

- Developer → Claude Code: prompts (evidence: `README.md`)
- Claude Code → Session Context: starts session (evidence: `plugin/hooks/session-start.js`)
- Session Context → Settings and Credentials: loads settings (evidence: `plugin/hooks/session-start.js`)
- Session Context → Project Configuration: loads project config (evidence: `plugin/hooks/session-start.js`)
- Session Context → Repository Container: selects container (evidence: `plugin/hooks/session-start.js`)
- Session Context → Browser Authentication: authenticates if needed (evidence: `plugin/hooks/session-start.js`)
- Session Context → Memory API Client: fetches profile (evidence: `plugin/hooks/session-start.js`)
- Memory API Client → Supermemory Service: requests profile (evidence: `plugin/hooks/lib/api.js`)
- Session Context → Claude Code: injects context (evidence: `plugin/hooks/session-start.js`)
- Claude Code → Reasoned Recall: submits prompt (evidence: `README.md`)
- Reasoned Recall → Settings and Credentials: reads recall config (evidence: `plugin/hooks/recall-directive.js`)
- Reasoned Recall → Project Configuration: loads project config (evidence: `plugin/hooks/recall-directive.js`)
- Reasoned Recall → Repository Container: selects container (evidence: `plugin/hooks/recall-directive.js`)
- Reasoned Recall → Memory API Client: searches profile (evidence: `plugin/hooks/recall-directive.js`)
- Reasoned Recall → Claude Code: injects matches (evidence: `plugin/hooks/recall-directive.js`)
- Claude Code → Auto Capture: ends session (evidence: `README.md`)
- Auto Capture → Transcript Processing: processes transcript (evidence: `plugin/hooks/capture.js`)
- Auto Capture → Settings and Credentials: reads capture settings (evidence: `plugin/hooks/capture.js`)
- Auto Capture → Repository Container: selects container (evidence: `plugin/hooks/capture.js`)
- Auto Capture → Memory API Client: saves memories (evidence: `plugin/hooks/capture.js`)
- Memory API Client → Supermemory Service: writes documents (evidence: `plugin/hooks/lib/api.js`)
- Developer → Plugin Commands: runs commands (evidence: `README.md`)
- Plugin Commands → Project Configuration: configures project
- Developer → Memory Tool Proxy: requests search or save (evidence: `README.md`)
- Memory Tool Proxy → Memory API Client: uses memory API (evidence: `plugin/hooks/mcp-proxy.js`)
- Developer → Context Gatherer: requests context gathering
- Recall Approval → Session Status State: updates recall state (evidence: `plugin/hooks/recall-approve.js`)
- Session Context → Session Status State: writes context state (evidence: `plugin/hooks/session-start.js`)
- Auto Capture → Session Status State: writes capture state (evidence: `plugin/hooks/capture.js`)
- Statusline Renderer → Session Status State: reads session state
- Auto Capture → Last Session Link: stores session link (evidence: `plugin/hooks/capture.js`)
- Session Context → Statusline Renderer: installs statusline (evidence: `plugin/hooks/session-start.js`)
- Settings and Credentials → Browser Authentication: loads credentials (evidence: `plugin/hooks/lib/settings.js`)
