# supermemoryai/codex-supermemory architecture

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

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

## Overview

codex-supermemory connects Codex CLI sessions to persistent Supermemory context. At session start it authenticates if needed and loads profile context; on substantive prompts it retrieves and injects relevant memories; when a turn ends it captures new transcript content. Separate capabilities include hosted MCP operations, repository-scoped containers, status/index skills, and a persistent terminal mark. Edges follow README statements or SOURCE INDEX references and excerpts; unsampled subsystem links are limited to documented behavior.

Main entry points: [`src/hooks/session-start.ts`](https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/session-start.ts) (Session start hook), [`src/hooks/recall.ts`](https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/recall.ts) (Prompt recall hook), [`src/services/capture.ts`](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/capture.ts) (Turn capture), [`src/services/client.ts`](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/client.ts) (Supermemory client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and identity"]
  node_cli["Installer CLI<br/>[cli.ts]"]
  node_config["Configuration<br/>[config.ts]"]
  node_auth["Browser authentication<br/>[auth.ts]"]
  node_tags["Container routing<br/>[tags.ts]"]
  node_session["Session identity<br/>[session.ts]"]
end

subgraph group_recall["Recall and context"]
  node_sessionstart["Session start hook<br/>[session-start.ts]"]
  node_recallhook["Prompt recall hook<br/>[recall.ts]"]
  node_hookclient["Hook recall client"]
  node_context["Context formatting<br/>[context.ts]"]
  node_cache["Seen-fact cache<br/>[factCache.ts]"]
end

subgraph group_capture["Capture and storage"]
  node_client["Supermemory client<br/>[client.ts]"]
  node_capture["Turn capture<br/>[capture.ts]"]
  node_flush["Stop hook<br/>[flush.ts]"]
  node_transcript["Transcript parsing<br/>[transcript.ts]"]
  node_signals["Signal filtering<br/>[signals.ts]"]
  node_tracker["Capture tracker<br/>[tracker.ts]"]
  node_privacy["Private-text redaction<br/>[privacy.ts]"]
end

subgraph group_integrations["Codex integrations"]
  node_mcp{{"Hosted MCP server"}}
  node_proxy["MCP proxy hook<br/>[mcp-proxy.ts]"]
  node_approval["Recall approval hook<br/>[recall-approve.ts]"]
  node_skills["Status skill<br/>[status.ts]"]
  node_indexskill["Index skill<br/>[SKILL.md]"]
  node_pet["Persistent CLI mark<br/>[pet.json]"]
end

node_codex(("Codex CLI"))
node_api{{"Supermemory API"}}

node_codex -->|"runs installer"| node_cli
node_cli -.->|"sets up"| node_config
node_codex -->|"starts session"| node_sessionstart
node_sessionstart -->|"starts auth"| node_auth
node_sessionstart -->|"resolves containers"| node_tags
node_sessionstart -->|"loads profile"| node_client
node_sessionstart -->|"formats context"| node_context
node_sessionstart -->|"tracks facts"| node_cache
node_codex -->|"submits prompt"| node_recallhook
node_recallhook -->|"resolves containers"| node_tags
node_recallhook -->|"gets session ID"| node_session
node_recallhook -->|"requests recall"| node_hookclient
node_recallhook -->|"filters seen facts"| node_cache
node_hookclient -->|"fetches profile"| node_api
node_hookclient -->|"uses result types"| node_client
node_sessionstart -->|"loads profile"| node_api
node_recallhook -->|"injects memories"| node_codex
node_codex -->|"ends turn"| node_flush
node_flush -->|"captures turn"| node_capture
node_flush -->|"provides client"| node_client
node_flush -->|"resolves containers"| node_tags
node_capture -->|"parses entries"| node_transcript
node_capture -->|"filters entries"| node_signals
node_capture -->|"checks progress"| node_tracker
node_capture -->|"saves memories"| node_client
node_capture -->|"uploads memories"| node_api
node_transcript -->|"redacts text"| node_privacy
node_client -->|"searches and writes"| node_api
node_codex -->|"invokes MCP"| node_proxy
node_proxy -->|"proxies requests"| node_mcp
node_codex -->|"runs tool hook"| node_approval
node_approval -->|"allows read tools"| node_mcp
node_codex -->|"runs status skill"| node_skills
node_codex -->|"runs index skill"| node_indexskill
node_indexskill -->|"saves via MCP"| node_mcp
node_cli -->|"installs badge"| node_pet
node_skills -->|"checks authentication"| node_auth
node_config -->|"loads credentials"| node_auth

click node_cli "https://github.com/supermemoryai/codex-supermemory/blob/main/src/cli.ts"
click node_config "https://github.com/supermemoryai/codex-supermemory/blob/main/src/config.ts"
click node_auth "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/auth.ts"
click node_tags "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/tags.ts"
click node_session "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/session.ts"
click node_sessionstart "https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/session-start.ts"
click node_recallhook "https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/recall.ts"
click node_hookclient "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/hookRecallClient.ts"
click node_context "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/context.ts"
click node_cache "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/factCache.ts"
click node_client "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/client.ts"
click node_capture "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/capture.ts"
click node_flush "https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/flush.ts"
click node_transcript "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/transcript.ts"
click node_signals "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/signals.ts"
click node_tracker "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/tracker.ts"
click node_privacy "https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/privacy.ts"
click node_proxy "https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/mcp-proxy.ts"
click node_approval "https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/recall-approve.ts"
click node_skills "https://github.com/supermemoryai/codex-supermemory/blob/main/src/skills/status.ts"
click node_indexskill "https://github.com/supermemoryai/codex-supermemory/blob/main/src/skills/supermemory-index/SKILL.md"
click node_pet "https://github.com/supermemoryai/codex-supermemory/blob/main/src/pet/pet.json"

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_cli,node_config,node_auth,node_tags,node_session toneBlue
class node_sessionstart,node_recallhook,node_hookclient,node_context,node_cache toneAmber
class node_client,node_capture,node_flush,node_transcript,node_signals,node_tracker,node_privacy,node_api toneMint
class node_mcp,node_proxy,node_approval,node_skills,node_indexskill,node_pet toneRose
class node_codex toneIndigo
```

## Components

### Setup and identity

- [Installer CLI](https://github.com/supermemoryai/codex-supermemory/blob/main/src/cli.ts): `src/cli.ts`
- [Configuration](https://github.com/supermemoryai/codex-supermemory/blob/main/src/config.ts): `src/config.ts`
- [Browser authentication](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/auth.ts): `src/services/auth.ts`
- [Container routing](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/tags.ts): `src/services/tags.ts`
- [Session identity](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/session.ts): `src/services/session.ts`

### Recall and context

- [Session start hook](https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/session-start.ts): `src/hooks/session-start.ts`
- [Prompt recall hook](https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/recall.ts): `src/hooks/recall.ts`
- [Hook recall client](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/hookRecallClient.ts): `src/services/hookRecallClient.ts`
- [Context formatting](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/context.ts): `src/services/context.ts`
- [Seen-fact cache](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/factCache.ts): `src/services/factCache.ts`

### Capture and storage

- [Supermemory client](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/client.ts): `src/services/client.ts`
- [Turn capture](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/capture.ts): `src/services/capture.ts`
- [Stop hook](https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/flush.ts): `src/hooks/flush.ts`
- [Transcript parsing](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/transcript.ts): `src/services/transcript.ts`
- [Signal filtering](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/signals.ts): `src/services/signals.ts`
- [Capture tracker](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/tracker.ts): `src/services/tracker.ts`
- [Private-text redaction](https://github.com/supermemoryai/codex-supermemory/blob/main/src/services/privacy.ts): `src/services/privacy.ts`

### Codex integrations

- **Hosted MCP server**
- [MCP proxy hook](https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/mcp-proxy.ts): `src/hooks/mcp-proxy.ts`
- [Recall approval hook](https://github.com/supermemoryai/codex-supermemory/blob/main/src/hooks/recall-approve.ts): `src/hooks/recall-approve.ts`
- [Status skill](https://github.com/supermemoryai/codex-supermemory/blob/main/src/skills/status.ts): `src/skills/status.ts`
- [Index skill](https://github.com/supermemoryai/codex-supermemory/blob/main/src/skills/supermemory-index/SKILL.md): `src/skills/supermemory-index/SKILL.md`
- [Persistent CLI mark](https://github.com/supermemoryai/codex-supermemory/blob/main/src/pet/pet.json): `src/pet/pet.json`

### Other components

- **Codex CLI**
- **Supermemory API**

## Connections

- Codex CLI → Installer CLI: runs installer (evidence: `README.md`)
- Installer CLI → Configuration: sets up (evidence: `src/cli.ts`)
- Codex CLI → Session start hook: starts session (evidence: `README.md`)
- Session start hook → Browser authentication: starts auth (evidence: `src/hooks/session-start.ts`)
- Session start hook → Container routing: resolves containers (evidence: `src/hooks/session-start.ts`)
- Session start hook → Supermemory client: loads profile (evidence: `src/hooks/session-start.ts`)
- Session start hook → Context formatting: formats context (evidence: `src/hooks/session-start.ts`)
- Session start hook → Seen-fact cache: tracks facts (evidence: `src/hooks/session-start.ts`)
- Codex CLI → Prompt recall hook: submits prompt (evidence: `README.md`)
- Prompt recall hook → Container routing: resolves containers (evidence: `src/hooks/recall.ts`)
- Prompt recall hook → Session identity: gets session ID (evidence: `src/hooks/recall.ts`)
- Prompt recall hook → Hook recall client: requests recall (evidence: `src/hooks/recall.ts`)
- Prompt recall hook → Seen-fact cache: filters seen facts (evidence: `src/hooks/recall.ts`)
- Hook recall client → Supermemory API: fetches profile (evidence: `src/services/hookRecallClient.ts`)
- Hook recall client → Supermemory client: uses result types (evidence: `src/services/hookRecallClient.ts`)
- Session start hook → Supermemory API: loads profile (evidence: `README.md`)
- Prompt recall hook → Codex CLI: injects memories (evidence: `README.md`)
- Codex CLI → Stop hook: ends turn (evidence: `README.md`)
- Stop hook → Turn capture: captures turn (evidence: `src/hooks/flush.ts`)
- Stop hook → Supermemory client: provides client (evidence: `src/hooks/flush.ts`)
- Stop hook → Container routing: resolves containers (evidence: `src/hooks/flush.ts`)
- Turn capture → Transcript parsing: parses entries (evidence: `src/services/capture.ts`)
- Turn capture → Signal filtering: filters entries (evidence: `src/services/capture.ts`)
- Turn capture → Capture tracker: checks progress (evidence: `src/services/capture.ts`)
- Turn capture → Supermemory client: saves memories (evidence: `src/services/capture.ts`)
- Turn capture → Supermemory API: uploads memories (evidence: `README.md`)
- Transcript parsing → Private-text redaction: redacts text (evidence: `src/services/transcript.ts`)
- Supermemory client → Supermemory API: searches and writes (evidence: `src/services/client.ts`)
- Codex CLI → MCP proxy hook: invokes MCP (evidence: `README.md`)
- MCP proxy hook → Hosted MCP server: proxies requests (evidence: `README.md`)
- Codex CLI → Recall approval hook: runs tool hook (evidence: `README.md`)
- Recall approval hook → Hosted MCP server: allows read tools (evidence: `README.md`)
- Codex CLI → Status skill: runs status skill (evidence: `README.md`)
- Codex CLI → Index skill: runs index skill (evidence: `README.md`)
- Index skill → Hosted MCP server: saves via MCP (evidence: `README.md`)
- Installer CLI → Persistent CLI mark: installs badge (evidence: `README.md`)
- Status skill → Browser authentication: checks authentication (evidence: `src/skills/status.ts`)
- Configuration → Browser authentication: loads credentials (evidence: `src/config.ts`)
