# ericaltenburg/claude-toc architecture

> Architecture diagram of the GitHub repository ericaltenburg/claude-toc, 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/ericaltenburg/claude-toc
- Repository: https://github.com/ericaltenburg/claude-toc
- Video tour (about a minute): https://gitdiagram.com/ericaltenburg/claude-toc/video

## Overview

claude-toc is local session memory for Claude Code: it records prompts, extracts dated facts from idle transcripts, indexes facts and prompt history, and exposes an on-demand search. The principal path runs from prompt submission through a silent sweep and extraction to the markdown corpus; queries refresh a disposable SQLite index before searching. The graph also includes documented status and spend reporting. Edges are limited to README statements and relationships visible in the supplied source index or excerpts; unsampled implementation details are not inferred.

Main entry points: [`src/extract/extractor.js`](https://github.com/ericaltenburg/claude-toc/blob/master/src/extract/extractor.js) (Fact extractor), [`src/search/search.js`](https://github.com/ericaltenburg/claude-toc/blob/master/src/search/search.js) (Search engine), [`src/cli/index.js`](https://github.com/ericaltenburg/claude-toc/blob/master/src/cli/index.js) (Command dispatcher), [`src/index/refresh.js`](https://github.com/ericaltenburg/claude-toc/blob/master/src/index/refresh.js) (Index refresh)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and extraction"]
  node_prompt_hook["Prompt hook<br/>[toc-prompt.mjs]"]
  node_sweep["Session sweep<br/>[sweep.js]"]
  node_discovery["Session discovery<br/>[known-sessions.js]"]
  node_transcript["Transcript reader<br/>[transcript.js]"]
  node_extractor["Fact extractor<br/>[extractor.js]"]
end

subgraph group_memory["Fact corpus"]
  node_topic_store["Topic corpus<br/>[topics.js]"]
  node_fact_format["Fact format<br/>[format.js]"]
  node_progress["Extraction progress<br/>[progress.js]"]
end

subgraph group_retrieval["Index and search"]
  node_index[("SQLite index<br/>[open.js]")]
  node_refresh["Index refresh<br/>[refresh.js]"]
  node_search["Search engine<br/>[search.js]"]
  node_search_skill["Search skill<br/>[SKILL.md]"]
end

subgraph group_operations["Commands and reporting"]
  node_cli["Command dispatcher<br/>[index.js]"]
  node_status["Status report<br/>[status.js]"]
  node_spend["Spend tracking<br/>[spend.js]"]
end

node_claude(("Claude Code"))
node_bedrock{{"Amazon Bedrock"}}
node_prompt_history["Claude prompt history"]

node_claude -->|"submits prompt"| node_prompt_hook
node_prompt_hook -->|"starts sweep"| node_sweep
node_sweep -->|"finds sessions"| node_discovery
node_discovery -->|"opens transcript"| node_transcript
node_extractor -->|"reads unread slice"| node_transcript
node_extractor -->|"requests extraction"| node_bedrock
node_extractor -->|"writes facts"| node_topic_store
node_extractor -->|"records progress"| node_progress
node_topic_store -->|"formats facts"| node_fact_format
node_search_skill -->|"offers on-demand search"| node_claude
node_claude -->|"requests search"| node_search
node_search -->|"queries index"| node_index
node_index -->|"refreshes before query"| node_refresh
node_refresh -->|"reads corpus"| node_topic_store
node_refresh -->|"indexes prompts"| node_prompt_history
node_cli -->|"dispatches search"| node_search
node_cli -->|"dispatches status"| node_status
node_cli -->|"dispatches spend"| node_spend
node_status -->|"checks search"| node_search
node_status -->|"reads index"| node_index

click node_prompt_hook "https://github.com/ericaltenburg/claude-toc/blob/master/hooks/toc-prompt.mjs"
click node_sweep "https://github.com/ericaltenburg/claude-toc/blob/master/src/extract/sweep.js"
click node_discovery "https://github.com/ericaltenburg/claude-toc/blob/master/src/sessions/known-sessions.js"
click node_transcript "https://github.com/ericaltenburg/claude-toc/blob/master/src/sessions/transcript.js"
click node_extractor "https://github.com/ericaltenburg/claude-toc/blob/master/src/extract/extractor.js"
click node_topic_store "https://github.com/ericaltenburg/claude-toc/blob/master/src/corpus/topics.js"
click node_fact_format "https://github.com/ericaltenburg/claude-toc/blob/master/src/corpus/format.js"
click node_progress "https://github.com/ericaltenburg/claude-toc/blob/master/src/sessions/progress.js"
click node_index "https://github.com/ericaltenburg/claude-toc/blob/master/src/index/open.js"
click node_refresh "https://github.com/ericaltenburg/claude-toc/blob/master/src/index/refresh.js"
click node_search "https://github.com/ericaltenburg/claude-toc/blob/master/src/search/search.js"
click node_search_skill "https://github.com/ericaltenburg/claude-toc/blob/master/skills/toc-search/SKILL.md"
click node_cli "https://github.com/ericaltenburg/claude-toc/blob/master/src/cli/index.js"
click node_status "https://github.com/ericaltenburg/claude-toc/blob/master/src/status/status.js"
click node_spend "https://github.com/ericaltenburg/claude-toc/blob/master/src/extract/spend.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_prompt_hook,node_sweep,node_discovery,node_transcript,node_extractor toneBlue
class node_topic_store,node_fact_format,node_progress toneAmber
class node_index,node_refresh,node_search,node_search_skill toneMint
class node_cli,node_status,node_spend toneRose
class node_claude,node_bedrock,node_prompt_history toneIndigo
```

## Components

### Capture and extraction

- [Prompt hook](https://github.com/ericaltenburg/claude-toc/blob/master/hooks/toc-prompt.mjs): `hooks/toc-prompt.mjs`
- [Session sweep](https://github.com/ericaltenburg/claude-toc/blob/master/src/extract/sweep.js): `src/extract/sweep.js`
- [Session discovery](https://github.com/ericaltenburg/claude-toc/blob/master/src/sessions/known-sessions.js): `src/sessions/known-sessions.js`
- [Transcript reader](https://github.com/ericaltenburg/claude-toc/blob/master/src/sessions/transcript.js): `src/sessions/transcript.js`
- [Fact extractor](https://github.com/ericaltenburg/claude-toc/blob/master/src/extract/extractor.js): `src/extract/extractor.js`

### Fact corpus

- [Topic corpus](https://github.com/ericaltenburg/claude-toc/blob/master/src/corpus/topics.js): `src/corpus/topics.js`
- [Fact format](https://github.com/ericaltenburg/claude-toc/blob/master/src/corpus/format.js): `src/corpus/format.js`
- [Extraction progress](https://github.com/ericaltenburg/claude-toc/blob/master/src/sessions/progress.js): `src/sessions/progress.js`

### Index and search

- [SQLite index](https://github.com/ericaltenburg/claude-toc/blob/master/src/index/open.js): `src/index/open.js`
- [Index refresh](https://github.com/ericaltenburg/claude-toc/blob/master/src/index/refresh.js): `src/index/refresh.js`
- [Search engine](https://github.com/ericaltenburg/claude-toc/blob/master/src/search/search.js): `src/search/search.js`
- [Search skill](https://github.com/ericaltenburg/claude-toc/blob/master/skills/toc-search/SKILL.md): `skills/toc-search/SKILL.md`

### Commands and reporting

- [Command dispatcher](https://github.com/ericaltenburg/claude-toc/blob/master/src/cli/index.js): `src/cli/index.js`
- [Status report](https://github.com/ericaltenburg/claude-toc/blob/master/src/status/status.js): `src/status/status.js`
- [Spend tracking](https://github.com/ericaltenburg/claude-toc/blob/master/src/extract/spend.js): `src/extract/spend.js`

### Other components

- **Claude Code**
- **Amazon Bedrock**
- **Claude prompt history**

## Connections

- Claude Code → Prompt hook: submits prompt (evidence: `README.md`)
- Prompt hook → Session sweep: starts sweep (evidence: `hooks/toc-prompt.mjs`)
- Session sweep → Session discovery: finds sessions (evidence: `src/extract/sweep.js`)
- Session discovery → Transcript reader: opens transcript (evidence: `src/sessions/known-sessions.js`)
- Fact extractor → Transcript reader: reads unread slice (evidence: `src/extract/extractor.js`)
- Fact extractor → Amazon Bedrock: requests extraction (evidence: `README.md`)
- Fact extractor → Topic corpus: writes facts (evidence: `src/extract/extractor.js`)
- Fact extractor → Extraction progress: records progress (evidence: `src/extract/extractor.js`)
- Topic corpus → Fact format: formats facts (evidence: `src/corpus/topics.js`)
- Search skill → Claude Code: offers on-demand search (evidence: `README.md`)
- Claude Code → Search engine: requests search (evidence: `README.md`)
- Search engine → SQLite index: queries index (evidence: `src/search/search.js`)
- SQLite index → Index refresh: refreshes before query (evidence: `src/index/open.js`)
- Index refresh → Topic corpus: reads corpus (evidence: `src/index/refresh.js`)
- Index refresh → Claude prompt history: indexes prompts (evidence: `README.md`)
- Command dispatcher → Search engine: dispatches search (evidence: `src/cli/index.js`)
- Command dispatcher → Status report: dispatches status (evidence: `src/cli/index.js`)
- Command dispatcher → Spend tracking: dispatches spend (evidence: `src/cli/index.js`)
- Status report → Search engine: checks search (evidence: `src/status/status.js`)
- Status report → SQLite index: reads index (evidence: `src/status/status.js`)
