How supermemoryai/codex-supermemory works
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: session-start.ts Session start hook · recall.ts Prompt recall hook · capture.ts Turn capture · client.ts Supermemory client
Components 25
Setup and identity
- Installer CLI
src/cli.ts - Configuration
src/config.ts - Browser authentication
src/services/auth.ts - Container routing
src/services/tags.ts - Session identity
src/services/session.ts
Recall and context
- Session start hook
src/hooks/session-start.ts - Prompt recall hook
src/hooks/recall.ts - Hook recall client
src/services/hookRecallClient.ts - Context formatting
src/services/context.ts - Seen-fact cache
src/services/factCache.ts
Capture and storage
- Supermemory client
src/services/client.ts - Turn capture
src/services/capture.ts - Stop hook
src/hooks/flush.ts - Transcript parsing
src/services/transcript.ts - Signal filtering
src/services/signals.ts - Capture tracker
src/services/tracker.ts - Private-text redaction
src/services/privacy.ts
Codex integrations
- Hosted MCP server
- MCP proxy hook
src/hooks/mcp-proxy.ts - Recall approval hook
src/hooks/recall-approve.ts - Status skill
src/skills/status.ts - Index skill
src/skills/supermemory-index/SKILL.md - Persistent CLI mark
src/pet/pet.json
Other components
- Codex CLI
- Supermemory API
Connections 38
- Codex CLI → Installer CLI: runs installer
README.md - Installer CLI → Configuration: sets up
src/cli.ts - Codex CLI → Session start hook: starts session
README.md - Session start hook → Browser authentication: starts auth
src/hooks/session-start.ts - Session start hook → Container routing: resolves containers
src/hooks/session-start.ts - Session start hook → Supermemory client: loads profile
src/hooks/session-start.ts - Session start hook → Context formatting: formats context
src/hooks/session-start.ts - Session start hook → Seen-fact cache: tracks facts
src/hooks/session-start.ts - Codex CLI → Prompt recall hook: submits prompt
README.md - Prompt recall hook → Container routing: resolves containers
src/hooks/recall.ts - Prompt recall hook → Session identity: gets session ID
src/hooks/recall.ts - Prompt recall hook → Hook recall client: requests recall
src/hooks/recall.ts - Prompt recall hook → Seen-fact cache: filters seen facts
src/hooks/recall.ts - Hook recall client → Supermemory API: fetches profile
src/services/hookRecallClient.ts - Hook recall client → Supermemory client: uses result types
src/services/hookRecallClient.ts - Session start hook → Supermemory API: loads profile
README.md - Prompt recall hook → Codex CLI: injects memories
README.md - Codex CLI → Stop hook: ends turn
README.md - Stop hook → Turn capture: captures turn
src/hooks/flush.ts - Stop hook → Supermemory client: provides client
src/hooks/flush.ts - Stop hook → Container routing: resolves containers
src/hooks/flush.ts - Turn capture → Transcript parsing: parses entries
src/services/capture.ts - Turn capture → Signal filtering: filters entries
src/services/capture.ts - Turn capture → Capture tracker: checks progress
src/services/capture.ts - Turn capture → Supermemory client: saves memories
src/services/capture.ts - Turn capture → Supermemory API: uploads memories
README.md - Transcript parsing → Private-text redaction: redacts text
src/services/transcript.ts - Supermemory client → Supermemory API: searches and writes
src/services/client.ts - Codex CLI → MCP proxy hook: invokes MCP
README.md - MCP proxy hook → Hosted MCP server: proxies requests
README.md - Codex CLI → Recall approval hook: runs tool hook
README.md - Recall approval hook → Hosted MCP server: allows read tools
README.md - Codex CLI → Status skill: runs status skill
README.md - Codex CLI → Index skill: runs index skill
README.md - Index skill → Hosted MCP server: saves via MCP
README.md - Installer CLI → Persistent CLI mark: installs badge
README.md - Status skill → Browser authentication: checks authentication
src/skills/status.ts - Configuration → Browser authentication: loads credentials
src/config.ts