How jwmcguire3/continuity-memory works
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: memory-model.js Canonical records · engine.js Memory engine · retrieval.js Memory retrieval · hierarchy-policy.js Hierarchical history
Components 21
Host integration
- Extension manifest
extension/manifest.json - Bootstrap
extension/index.js - Runtime initialization
extension/runtime.js - Plugin integration · Supports host installation and integration.
plugin/index.js
Runtime orchestration
- SillyTavern boundary · Accesses host APIs and current chat state.
extension/api.js - Memory engine · Coordinates extraction, catch-up, retrieval, reduction, and injection.
extension/engine.js - Model request boundary · Uses active connections, profiles, compatible endpoints, and OpenRouter.
extension/model-compatibility.js
Memory pipeline
- Canonical records · Structured records retain revisable source-backed memory.
extension/memory-model.js - Source integrity · Invalidates affected records after mutable chat history changes.
extension/fingerprint.js - Mutable state lifecycle · Protects scene state and preserves temporal source order.
extension/state-lifecycle.js - Extraction pipeline · Builds detailed L1 records from completed chat ranges.
extension/extraction-budget.js - Hierarchical history · Aggregates older records while recent uncovered chat remains raw.
extension/hierarchy-policy.js - Coverage gate · Only safely represented source ranges may be reduced.
extension/coverage.js
Retrieval and injection
- Retrieval query
extension/retrieval-query.js - Memory retrieval · Returns relevant records and chronology.
extension/retrieval.js - Semantic and embedding retrieval · Local matching with optional AI expansion and embedding fallback.
extension/semantic-retrieval.js - Prompt injection · Deduplicates and withholds records covered by the visible raw tail.
extension/prompt-manager-injection.js
Persistence and controls
- Per-chat storage · Persists split large-memory state through the host user-file API.
extension/file-storage.js - Portable snapshots · Fingerprint-validates snapshots and excludes embeddings.
extension/portable-state.js - Derived vector index · Separately stored, incrementally synchronized, and rebuildable.
extension/embedding-index.js - Memory controls · Provides inspection and reviewed correction previews.
extension/ui.js
Connections 26
- 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