# jwmcguire3/continuity-memory architecture

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

- Interactive diagram: https://gitdiagram.com/jwmcguire3/continuity-memory
- Repository: https://github.com/jwmcguire3/continuity-memory

## Overview

#### Purpose and host integration
Continuity Memory is a browser-side SillyTavern extension providing per-chat, structured and revisable long-term roleplay/simulation memory. Its extension manifest and bootstrap are `extension/manifest.json`, `extension/index.js`, and `extension/runtime.js`. A minimal plugin package (`plugin/index.js`) appears to support host installation/integration rather than a separate service.

#### Runtime orchestration and request boundary
`extension/engine.js` is the central coordinator for chat lifecycle, background extraction, catch-up gating, retrieval, context reduction, and generation-time injection. `extension/api.js` and `extension/loader.js` form the boundary to SillyTavern APIs and host state. Model calls are mediated through `extension/model-compatibility.js`, `extension/profile-request-policy.js`, and `extension/prompts.js`, supporting the active connection, connection profiles, OpenAI-compatible endpoints, and OpenRouter without changing the main RP request settings.

#### Memory model, source integrity, and lifecycle
Canonical memory records and revision semantics live in `extension/memory-model.js`, `extension/memory-correction.js`, and `extension/reconciliation-policy.js`. Records retain source ranges and fingerprints (`extension/fingerprint.js`), enabling invalidation after edits, swipes, deletions, or branch changes. `extension/state-lifecycle.js` applies fail-closed handling for mutable scene state; `extension/temporal-anchors.js` preserves source-order temporal references without inventing chronology.

#### Extraction and hierarchical history
The processing pipeline turns completed chat ranges into structured records and chronological levels. Extraction constraints and focus/background behavior are governed by `extension/extraction-budget.js`, `extension/hierarchy-policy.js`, and `extension/l1-policy.js`. L1 records represent detailed ranges; later aggregation produces L2/L3 history, while uncovered recent messages remain raw. `extension/coverage.js` determines whether source chat is safely represented before it can be reduced.

#### Retrieval and prompt assembly
At generation time, the system derives a query from current context (`extension/retrieval-query.js`), retrieves canonical records and chronology (`extension/retrieval.js`), and injects a budgeted, deduplicated memory block. `extension/injection-budget.js`, `extension/injection-placement.js`, and `extension/prompt-manager-injection.js` define the prompt boundary. Raw recent chat takes precedence: records wholly covered by the visible tail are withheld, and incomplete/invalid coverage leaves original messages in context.

#### Retrieval modes and embeddings
Local deterministic matching and optional AI query expansion are implemented by `extension/semantic-retrieval.js` and `extension/semantic-terms.js`. Embedding-hybrid retrieval uses `extension/embedding-provider.js` and `extension/embedding-index.js`; the vector index is derived, separately stored, incrementally synchronized, rebuildable, and non-portable. Failures fall back to local retrieval.

#### Persistence, portability, and user controls
Per-chat state is persisted through SillyTavern’s authenticated user-file API via `extension/file-storage.js`, with large-memory splitting handled internally. `extension/portable-state.js` and `extension/portable.js` export/import fingerprint-validated snapshots; embeddings are excluded. The interactive surfaces are `extension/ui.js`, `extension/memory-viewer.js`, `extension/settings.html`, and `extension/settings.js`, including inspection and reviewed correction previews.

Main entry points: [`extension/memory-model.js`](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/memory-model.js) (Canonical records), [`extension/engine.js`](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/engine.js) (Memory engine), [`extension/retrieval.js`](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/retrieval.js) (Memory retrieval), [`extension/hierarchy-policy.js`](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/hierarchy-policy.js) (Hierarchical history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host integration"]
  node_manifest["Extension manifest<br/>extension metadata<br/>[manifest.json]"]
  node_bootstrap["Bootstrap<br/>extension entry<br/>[index.js]"]
  node_runtime_init["Runtime initialization<br/>host runtime<br/>[runtime.js]"]
  node_plugin["Plugin integration<br/>host plugin<br/>[index.js]"]
end

subgraph group_runtime["Runtime orchestration"]
  node_host_boundary["SillyTavern boundary<br/>host API adapter<br/>[api.js]"]
  node_engine{{"Memory engine<br/>lifecycle coordinator<br/>[engine.js]"}}
  node_model_boundary["Model request boundary<br/>model compatibility"]
end

subgraph group_memory["Memory pipeline"]
  node_memory_records[("Canonical records<br/>memory model and revisions<br/>[memory-model.js]")]
  node_source_integrity["Source integrity<br/>fingerprints and reconciliation<br/>[fingerprint.js]"]
  node_state_lifecycle["Mutable state lifecycle<br/>fail-closed state<br/>[state-lifecycle.js]"]
  node_extraction["Extraction pipeline<br/>range-to-record processing"]
  node_hierarchy["Hierarchical history<br/>L1/L2/L3 aggregation"]
  node_coverage["Coverage gate<br/>safe reduction policy<br/>[coverage.js]"]
end

subgraph group_generation["Retrieval and injection"]
  node_query["Retrieval query<br/>context-derived query<br/>[retrieval-query.js]"]
  node_retrieval{{"Memory retrieval<br/>canonical retrieval<br/>[retrieval.js]"}}
  node_semantic["Semantic and embedding retrieval<br/>hybrid retrieval"]
  node_prompt_injection["Prompt injection<br/>budgeted memory block"]
end

subgraph group_storage["Persistence and controls"]
  node_chat_storage[("Per-chat storage<br/>authenticated user files<br/>[file-storage.js]")]
  node_portable["Portable snapshots<br/>import/export<br/>[portable-state.js]"]
  node_embedding_index[("Derived vector index<br/>non-portable embeddings<br/>[embedding-index.js]")]
  node_ui["Memory controls<br/>settings and viewer<br/>[ui.js]"]
end

node_manifest -->|"declares"| node_bootstrap
node_bootstrap -->|"starts"| node_runtime_init
node_plugin -->|"integrates with"| node_host_boundary
node_runtime_init -->|"initializes"| node_engine
node_host_boundary -->|"chat state and lifecycle events"| node_engine
node_engine -->|"model work"| node_model_boundary
node_engine -->|"processes completed ranges"| node_extraction
node_extraction -->|"creates L1 records"| node_memory_records
node_memory_records -->|"older records aggregate"| node_hierarchy
node_source_integrity -->|"validates and invalidates"| node_memory_records
node_state_lifecycle -->|"guards mutable state"| node_memory_records
node_coverage -->|"permits safe reduction"| node_hierarchy
node_engine -->|"at generation"| node_query
node_query -->|"queries"| node_retrieval
node_memory_records -->|"canonical corpus"| node_retrieval
node_hierarchy -->|"chronology"| node_retrieval
node_semantic -->|"hybrid ranking and fallback"| node_retrieval
node_embedding_index -.->|"optional vectors"| node_semantic
node_retrieval -->|"selected memory"| node_prompt_injection
node_coverage -->|"raw-tail precedence"| node_prompt_injection
node_prompt_injection -->|"generation context"| node_engine
node_memory_records -->|"persists per chat"| node_chat_storage
node_chat_storage -->|"exports/imports"| node_portable
node_memory_records -.->|"synchronizes derived index"| node_embedding_index
node_ui -->|"user actions and corrections"| node_engine
node_ui -->|"inspects records"| node_memory_records

click node_manifest "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/manifest.json"
click node_bootstrap "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/index.js"
click node_runtime_init "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/runtime.js"
click node_plugin "https://github.com/jwmcguire3/continuity-memory/blob/main/plugin/index.js"
click node_host_boundary "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/api.js"
click node_engine "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/engine.js"
click node_model_boundary "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/model-compatibility.js"
click node_memory_records "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/memory-model.js"
click node_source_integrity "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/fingerprint.js"
click node_state_lifecycle "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/state-lifecycle.js"
click node_extraction "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/extraction-budget.js"
click node_hierarchy "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/hierarchy-policy.js"
click node_coverage "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/coverage.js"
click node_query "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/retrieval-query.js"
click node_retrieval "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/retrieval.js"
click node_semantic "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/semantic-retrieval.js"
click node_prompt_injection "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/prompt-manager-injection.js"
click node_chat_storage "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/file-storage.js"
click node_portable "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/portable-state.js"
click node_embedding_index "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/embedding-index.js"
click node_ui "https://github.com/jwmcguire3/continuity-memory/blob/main/extension/ui.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_manifest,node_bootstrap,node_runtime_init,node_plugin toneBlue
class node_host_boundary,node_engine,node_model_boundary toneAmber
class node_memory_records,node_source_integrity,node_state_lifecycle,node_extraction,node_hierarchy,node_coverage toneMint
class node_query,node_retrieval,node_semantic,node_prompt_injection toneRose
class node_chat_storage,node_portable,node_embedding_index,node_ui toneIndigo
```

## Components

### Host integration

- [Extension manifest](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/manifest.json): extension metadata · `extension/manifest.json`
- [Bootstrap](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/index.js): extension entry · `extension/index.js`
- [Runtime initialization](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/runtime.js): host runtime · `extension/runtime.js`
- [Plugin integration](https://github.com/jwmcguire3/continuity-memory/blob/main/plugin/index.js): host plugin · Supports host installation and integration. · `plugin/index.js`

### Runtime orchestration

- [SillyTavern boundary](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/api.js): host API adapter · Accesses host APIs and current chat state. · `extension/api.js`
- [Memory engine](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/engine.js): lifecycle coordinator · Coordinates extraction, catch-up, retrieval, reduction, and injection. · `extension/engine.js`
- [Model request boundary](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/model-compatibility.js): model compatibility · Uses active connections, profiles, compatible endpoints, and OpenRouter. · `extension/model-compatibility.js`

### Memory pipeline

- [Canonical records](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/memory-model.js): memory model and revisions · Structured records retain revisable source-backed memory. · `extension/memory-model.js`
- [Source integrity](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/fingerprint.js): fingerprints and reconciliation · Invalidates affected records after mutable chat history changes. · `extension/fingerprint.js`
- [Mutable state lifecycle](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/state-lifecycle.js): fail-closed state · Protects scene state and preserves temporal source order. · `extension/state-lifecycle.js`
- [Extraction pipeline](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/extraction-budget.js): range-to-record processing · Builds detailed L1 records from completed chat ranges. · `extension/extraction-budget.js`
- [Hierarchical history](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/hierarchy-policy.js): L1/L2/L3 aggregation · Aggregates older records while recent uncovered chat remains raw. · `extension/hierarchy-policy.js`
- [Coverage gate](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/coverage.js): safe reduction policy · Only safely represented source ranges may be reduced. · `extension/coverage.js`

### Retrieval and injection

- [Retrieval query](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/retrieval-query.js): context-derived query · `extension/retrieval-query.js`
- [Memory retrieval](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/retrieval.js): canonical retrieval · Returns relevant records and chronology. · `extension/retrieval.js`
- [Semantic and embedding retrieval](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/semantic-retrieval.js): hybrid retrieval · Local matching with optional AI expansion and embedding fallback. · `extension/semantic-retrieval.js`
- [Prompt injection](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/prompt-manager-injection.js): budgeted memory block · Deduplicates and withholds records covered by the visible raw tail. · `extension/prompt-manager-injection.js`

### Persistence and controls

- [Per-chat storage](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/file-storage.js): authenticated user files · Persists split large-memory state through the host user-file API. · `extension/file-storage.js`
- [Portable snapshots](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/portable-state.js): import/export · Fingerprint-validates snapshots and excludes embeddings. · `extension/portable-state.js`
- [Derived vector index](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/embedding-index.js): non-portable embeddings · Separately stored, incrementally synchronized, and rebuildable. · `extension/embedding-index.js`
- [Memory controls](https://github.com/jwmcguire3/continuity-memory/blob/main/extension/ui.js): settings and viewer · Provides inspection and reviewed correction previews. · `extension/ui.js`

## Connections

- Extension manifest → Bootstrap: declares
- Bootstrap → Runtime initialization: starts
- Plugin integration → SillyTavern boundary: integrates with
- Runtime initialization → Memory engine: initializes
- SillyTavern boundary → Memory engine: chat state and lifecycle events
- Memory engine → Model request boundary: model work
- Memory engine → Extraction pipeline: processes completed ranges
- Extraction pipeline → Canonical records: creates L1 records
- Canonical records → Hierarchical history: older records aggregate
- Source integrity → Canonical records: validates and invalidates
- Mutable state lifecycle → Canonical records: guards mutable state
- Coverage gate → Hierarchical history: permits safe reduction
- Memory engine → Retrieval query: at generation
- Retrieval query → Memory retrieval: queries
- Canonical records → Memory retrieval: canonical corpus
- Hierarchical history → Memory retrieval: chronology
- Semantic and embedding retrieval → Memory retrieval: hybrid ranking and fallback
- Derived vector index → Semantic and embedding retrieval: optional vectors
- Memory retrieval → Prompt injection: selected memory
- Coverage gate → Prompt injection: raw-tail precedence
- Prompt injection → Memory engine: generation context
- Canonical records → Per-chat storage: persists per chat
- Per-chat storage → Portable snapshots: exports/imports
- Canonical records → Derived vector index: synchronizes derived index
- Memory controls → Memory engine: user actions and corrections
- Memory controls → Canonical records: inspects records