# nekyialabs/resonant-archive architecture

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

- Interactive diagram: https://gitdiagram.com/nekyialabs/resonant-archive
- Repository: https://github.com/nekyialabs/resonant-archive

## Overview

resonant-archive pairs Chronicle, a Claude Code compaction and session-mirroring mod, with a local conversation archive. The main archive workflow imports conversation sources, normalizes and redacts records, stores them in PostgreSQL, optionally adds local embeddings, then serves hybrid search and recall through the CLI or MCP. Chronicle can also recall from its mirror and, when configured, the archive. The graph preserves documented capabilities and the sampled module boundaries; unsampled Chronicle internals and some CLI wiring are represented only where the README or source index supports them.

Main entry points: [`resonant_archive/cli.py`](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/cli.py) (Archive CLI), [`resonant_archive/search/engine.py`](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/engine.py) (Search engine), [`resonant_archive/pipeline.py`](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/pipeline.py) (Import pipeline), [`resonant_archive/search/recall.py`](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/recall.py) (Recall interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chronicle["Chronicle mod"]
  node_chronicle["Chronicle hooks<br/>[register.ts]"]
  node_mirror["Session mirror<br/>[register.ts]"]
end

subgraph group_ingest["Archive ingestion"]
  node_archive_cli["Archive CLI<br/>[cli.py]"]
  node_commands["Import commands<br/>[commands.py]"]
  node_registry["Importer registry<br/>[__init__.py]"]
  node_source_importers["Source importers"]
  node_import_contract["Importer records<br/>[base.py]"]
  node_safe_read["Safe input reads<br/>[safety.py]"]
  node_pipeline["Import pipeline<br/>[pipeline.py]"]
  node_redaction["Secret redaction<br/>[redact.py]"]
  node_textio["Text I/O<br/>[textio.py]"]
  node_timeutil["Time utilities<br/>[timeutil.py]"]
end

subgraph group_storage["Archive storage"]
  node_config["Configuration<br/>[config.py]"]
  node_database["Database setup<br/>[db.py]"]
  node_postgres[("PostgreSQL archive")]
  node_fsutil["Filesystem utilities<br/>[fsutil.py]"]
end

subgraph group_search["Search and recall"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_searcher["Search engine<br/>[engine.py]"]
  node_search_logic["Search ranking<br/>[core.py]"]
  node_search_format["Result formatting<br/>[format.py]"]
  node_recall["Recall interface<br/>[recall.py]"]
  node_embed_search["Query embedding<br/>[embedder.py]"]
end

subgraph group_embedding["Local embeddings"]
  node_embed_client["Embedding client<br/>[client.py]"]
  node_embed_server["Embed server<br/>[server.py]"]
  node_embedder["Local embedder<br/>[nomic.py]"]
  node_model_fetch["Model fetch<br/>[fetch.py]"]
  node_embed_paths["Model paths<br/>[paths.py]"]
end

node_person(("User"))
node_claude["Claude Code"]
node_model_host["Hugging Face"]

node_person -->|"uses"| node_claude
node_claude -->|"runs hooks"| node_chronicle
node_chronicle -->|"mirrors sessions"| node_mirror
node_person -->|"runs commands"| node_archive_cli
node_archive_cli -->|"dispatches"| node_commands
node_commands -->|"selects importer"| node_registry
node_registry -->|"loads formats"| node_source_importers
node_source_importers -->|"produces records"| node_import_contract
node_source_importers -->|"checks input"| node_safe_read
node_commands -->|"imports units"| node_pipeline
node_pipeline -->|"redacts records"| node_redaction
node_pipeline -->|"writes records"| node_postgres
node_pipeline -->|"consumes records"| node_import_contract
node_archive_cli -->|"initializes archive"| node_database
node_database -->|"resolves connection"| node_config
node_database -->|"migrates schema"| node_postgres
node_archive_cli -->|"starts server"| node_mcp
node_mcp -->|"serves search"| node_searcher
node_searcher -->|"queries archive"| node_postgres
node_searcher -->|"ranks results"| node_search_logic
node_searcher -->|"formats results"| node_search_format
node_archive_cli -->|"runs recall"| node_recall
node_recall -->|"executes queries"| node_searcher
node_recall -->|"searches mirror"| node_mirror
node_recall -->|"searches archive"| node_postgres
node_chronicle -.->|"invokes archive recall"| node_recall
node_archive_cli -->|"backfills vectors"| node_embed_client
node_searcher -->|"embeds query"| node_embed_search
node_embed_search -->|"requests vectors"| node_embed_client
node_embed_client -->|"posts locally"| node_embed_server
node_embed_client -->|"loads fallback"| node_embedder
node_embed_server -->|"computes vectors"| node_embedder
node_embed_server -->|"checks model files"| node_model_fetch
node_model_fetch -->|"downloads model"| node_model_host
node_embed_client -->|"resolves endpoint"| node_embed_paths
node_model_fetch -->|"resolves model path"| node_embed_paths
node_embed_paths -->|"uses data paths"| node_config
node_pipeline -.->|"reads text"| node_textio
node_source_importers -->|"normalizes timestamps"| node_timeutil
node_model_fetch -->|"replaces verified files"| node_fsutil

click node_chronicle "https://github.com/nekyialabs/resonant-archive/blob/main/claude-code/chronicle/hooks/register.ts"
click node_mirror "https://github.com/nekyialabs/resonant-archive/blob/main/claude-code/chronicle/hooks/register.ts"
click node_archive_cli "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/cli.py"
click node_commands "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/commands.py"
click node_registry "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/importers/__init__.py"
click node_source_importers "https://github.com/nekyialabs/resonant-archive/tree/main/resonant_archive/importers"
click node_import_contract "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/importers/base.py"
click node_safe_read "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/importers/safety.py"
click node_pipeline "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/pipeline.py"
click node_redaction "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/redact.py"
click node_config "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/config.py"
click node_database "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/db.py"
click node_mcp "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/mcp_server.py"
click node_searcher "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/engine.py"
click node_search_logic "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/core.py"
click node_search_format "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/format.py"
click node_recall "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/recall.py"
click node_embed_client "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/embed/client.py"
click node_embed_server "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/embed/server.py"
click node_embedder "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/embed/nomic.py"
click node_model_fetch "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/embed/fetch.py"
click node_embed_paths "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/embed/paths.py"
click node_embed_search "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/embedder.py"
click node_fsutil "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/fsutil.py"
click node_textio "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/textio.py"
click node_timeutil "https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/timeutil.py"

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_chronicle,node_mirror,node_person toneBlue
class node_archive_cli,node_commands,node_registry,node_source_importers,node_import_contract,node_safe_read,node_pipeline,node_redaction,node_textio,node_timeutil toneAmber
class node_config,node_database,node_postgres,node_fsutil toneMint
class node_mcp,node_searcher,node_search_logic,node_search_format,node_recall,node_embed_search toneRose
class node_embed_client,node_embed_server,node_embedder,node_model_fetch,node_embed_paths,node_claude,node_model_host toneIndigo
```

## Components

### Chronicle mod

- [Chronicle hooks](https://github.com/nekyialabs/resonant-archive/blob/main/claude-code/chronicle/hooks/register.ts): `claude-code/chronicle/hooks/register.ts`
- [Session mirror](https://github.com/nekyialabs/resonant-archive/blob/main/claude-code/chronicle/hooks/register.ts): `claude-code/chronicle/hooks/register.ts`

### Archive ingestion

- [Archive CLI](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/cli.py): `resonant_archive/cli.py`
- [Import commands](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/commands.py): `resonant_archive/commands.py`
- [Importer registry](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/importers/__init__.py): `resonant_archive/importers/__init__.py`
- [Source importers](https://github.com/nekyialabs/resonant-archive/tree/main/resonant_archive/importers): `resonant_archive/importers`
- [Importer records](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/importers/base.py): `resonant_archive/importers/base.py`
- [Safe input reads](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/importers/safety.py): `resonant_archive/importers/safety.py`
- [Import pipeline](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/pipeline.py): `resonant_archive/pipeline.py`
- [Secret redaction](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/redact.py): `resonant_archive/redact.py`
- [Text I/O](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/textio.py): `resonant_archive/textio.py`
- [Time utilities](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/timeutil.py): `resonant_archive/timeutil.py`

### Archive storage

- [Configuration](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/config.py): `resonant_archive/config.py`
- [Database setup](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/db.py): `resonant_archive/db.py`
- **PostgreSQL archive**
- [Filesystem utilities](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/fsutil.py): `resonant_archive/fsutil.py`

### Search and recall

- [MCP server](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/mcp_server.py): `resonant_archive/mcp_server.py`
- [Search engine](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/engine.py): `resonant_archive/search/engine.py`
- [Search ranking](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/core.py): `resonant_archive/search/core.py`
- [Result formatting](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/format.py): `resonant_archive/search/format.py`
- [Recall interface](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/recall.py): `resonant_archive/search/recall.py`
- [Query embedding](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/search/embedder.py): `resonant_archive/search/embedder.py`

### Local embeddings

- [Embedding client](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/embed/client.py): `resonant_archive/embed/client.py`
- [Embed server](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/embed/server.py): `resonant_archive/embed/server.py`
- [Local embedder](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/embed/nomic.py): `resonant_archive/embed/nomic.py`
- [Model fetch](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/embed/fetch.py): `resonant_archive/embed/fetch.py`
- [Model paths](https://github.com/nekyialabs/resonant-archive/blob/main/resonant_archive/embed/paths.py): `resonant_archive/embed/paths.py`

### Other components

- **User**
- **Claude Code**
- **Hugging Face**

## Connections

- User → Claude Code: uses (evidence: `README.md`)
- Claude Code → Chronicle hooks: runs hooks (evidence: `README.md`)
- Chronicle hooks → Session mirror: mirrors sessions (evidence: `README.md`)
- User → Archive CLI: runs commands (evidence: `README.md`)
- Archive CLI → Import commands: dispatches (evidence: `resonant_archive/cli.py`)
- Import commands → Importer registry: selects importer (evidence: `resonant_archive/commands.py`)
- Importer registry → Source importers: loads formats (evidence: `resonant_archive/importers/__init__.py`)
- Source importers → Importer records: produces records (evidence: `resonant_archive/importers/base.py`)
- Source importers → Safe input reads: checks input (evidence: `resonant_archive/importers/base.py`)
- Import commands → Import pipeline: imports units (evidence: `resonant_archive/commands.py`)
- Import pipeline → Secret redaction: redacts records (evidence: `resonant_archive/pipeline.py`)
- Import pipeline → PostgreSQL archive: writes records (evidence: `resonant_archive/pipeline.py`)
- Import pipeline → Importer records: consumes records (evidence: `resonant_archive/pipeline.py`)
- Archive CLI → Database setup: initializes archive (evidence: `resonant_archive/cli.py`)
- Database setup → Configuration: resolves connection (evidence: `resonant_archive/db.py`)
- Database setup → PostgreSQL archive: migrates schema (evidence: `resonant_archive/db.py`)
- Archive CLI → MCP server: starts server (evidence: `resonant_archive/cli.py`)
- MCP server → Search engine: serves search (evidence: `resonant_archive/mcp_server.py`)
- Search engine → PostgreSQL archive: queries archive (evidence: `resonant_archive/search/engine.py`)
- Search engine → Search ranking: ranks results (evidence: `resonant_archive/search/engine.py`)
- Search engine → Result formatting: formats results (evidence: `resonant_archive/search/format.py`)
- Archive CLI → Recall interface: runs recall (evidence: `resonant_archive/cli.py`)
- Recall interface → Search engine: executes queries (evidence: `resonant_archive/search/recall.py`)
- Recall interface → Session mirror: searches mirror (evidence: `README.md`)
- Recall interface → PostgreSQL archive: searches archive (evidence: `README.md`)
- Chronicle hooks → Recall interface: invokes archive recall (evidence: `README.md`)
- Archive CLI → Embedding client: backfills vectors (evidence: `resonant_archive/cli.py`)
- Search engine → Query embedding: embeds query (evidence: `resonant_archive/search/engine.py`)
- Query embedding → Embedding client: requests vectors (evidence: `resonant_archive/search/embedder.py`)
- Embedding client → Embed server: posts locally (evidence: `resonant_archive/embed/client.py`)
- Embedding client → Local embedder: loads fallback (evidence: `resonant_archive/embed/client.py`)
- Embed server → Local embedder: computes vectors (evidence: `resonant_archive/embed/server.py`)
- Embed server → Model fetch: checks model files (evidence: `resonant_archive/embed/server.py`)
- Model fetch → Hugging Face: downloads model (evidence: `resonant_archive/embed/fetch.py`)
- Embedding client → Model paths: resolves endpoint (evidence: `resonant_archive/embed/client.py`)
- Model fetch → Model paths: resolves model path (evidence: `resonant_archive/embed/fetch.py`)
- Model paths → Configuration: uses data paths (evidence: `resonant_archive/embed/paths.py`)
- Import pipeline → Text I/O: reads text
- Source importers → Time utilities: normalizes timestamps (evidence: `resonant_archive/importers/base.py`)
- Model fetch → Filesystem utilities: replaces verified files (evidence: `resonant_archive/embed/fetch.py`)