Continuity Engine

A lightweight Python library for preserving useful conversational continuity across separate AI sessions.

Continuity Engine gives AI applications a deterministic persistence layer for information that should survive beyond a single conversation. Instead of relying entirely on a language model to reconstruct previous context, applications can explicitly store continuity information and retrieve it later.

Project status: Early-stage standalone extraction from continuity architecture originally developed for Echo, a local AI assistant. APIs and architecture may evolve.

Why It Exists

Most conversational AI sessions begin with little or no awareness of what happened previously.

For assistants that span multiple sessions, useful information can include:

• what the user was working on
• preferences established earlier
• project milestones
• unfinished tasks
• previous decisions
• context needed for the next conversation

Continuity Engine separates persistent application memory from language-model reasoning.

The application explicitly stores structured continuity data. The engine persists that information locally and retrieves it deterministically when a future session needs it.

Features

Version 0.2 includes:

• persistent JSONL storage
• structured Memory objects
• automatically generated UUIDs
• timezone-aware UTC timestamps
• richer structured memory fields
• optional session IDs, sources, roles, source text, and metadata
• source timestamps and confidence values
• active/archived status support
• complete memory history
• filtering by type, subtype, status, and session ID
• latest-memory retrieval with filters
• deterministic keyword search
• deterministic relevance ranking with retrieve()
• empty-store handling
• executable continuity demo
• automated unit tests
• no third-party dependencies

Architecture

Application / AI Assistant
          |
          v
  ContinuityEngine
          |
          |  save()
          |  history()
          |  latest()
          |  search()
          |  retrieve()
          |
          +------------------+
          |                  |
          v                  v
   JSONLStorage        Ranking Logic
          |
          v
      JSONL File

Memory objects move through the engine
as structured continuity records.

The language model is not the database.

Continuity Engine treats persistence and retrieval as application responsibilities, allowing an LLM to focus on reasoning and conversation.

Requirements

• Python 3.10+
• No external packages required for v0.2

Quick Start

From the repository root:

python -m examples.basic_demo

Example output:

=== Session 1 ===
Saved: Next time, remind me that we're working on the memory system.

=== Session 2 ===
Recovered: Next time, remind me that we're working on the memory system.

The demo creates one engine instance, stores continuity information, then creates a new engine instance that retrieves the information from disk.

That simulates continuity across separate AI sessions.

Basic Usage

from continuity import ContinuityEngine, Memory

engine = ContinuityEngine("data/memories.jsonl")

engine.save(
    Memory(
        type="project",
        subtype="milestone",
        content="Next time, remind me that we're working on the memory system.",
        session_id="session-001",
        source_role="user",
        status="active",
    )
)

latest = engine.latest()

if latest:
    print(latest.content)

Search Stored Continuity

Simple deterministic search:

results = engine.search("memory system")

for memory in results:
    print(memory.content)

Search is case-insensitive and requires every query term to appear in the stored memory's type or content.

Ranked Retrieval

Version 0.2 adds deterministic relevance ranking:

results = engine.retrieve("memory system", limit=3)

for memory in results:
    print(memory.content)

retrieve() scores stored memories using keyword overlap and continuity-oriented signals.

It does not require:

• an LLM
• embeddings
• a vector database
• external APIs

Filtering

Stored memory history can be filtered by:

• type
• subtype
• status
• session_id

Example:

project_memories = engine.history(
    type="project",
    subtype="milestone",
    status="active",
)

Filters can also be combined.

Latest Matching Memory

latest() supports the same filters:

latest_preference = engine.latest(
    type="preference",
    status="active",
)

When available, source_timestamp is used to determine recency.

If no matching memory exists, latest() returns None.

Memory Model

A Memory can contain:

• content
• type
• subtype
• subject
• session_id
• source
• source_timestamp
• source_role
• source_text
• confidence
• status
• supersedes
• metadata
• id
• timestamp

Only content is required.

IDs and timestamps are generated automatically unless explicitly supplied.

Example:

Memory(
    type="explicit_memory",
    subtype="continuity_phrase",
    subject="continuity test",
    content="midnight sunflower",
    session_id="session-002",
    source_role="user",
    source_text="The continuity phrase is midnight sunflower",
    confidence=1.0,
    status="active",
)

Public API

Version 0.2 keeps the API intentionally small:

engine.save(memory)
engine.history()
engine.latest()
engine.search(query)
engine.retrieve(query, limit=3)

save(memory)

Persists a Memory to the JSONL store.

history()

Returns stored memories in insertion order.

Optional filters:

engine.history(
    type="project",
    subtype="milestone",
    status="active",
    session_id="session-001",
)

latest()

Returns the most recent matching memory, or None.

Supports the same filters as history().

search(query)

Performs simple deterministic keyword matching.

retrieve(query, limit=3)

Returns relevant memories ranked by deterministic relevance scoring.

Running Tests

Run the complete test suite from the repository root:

python -m unittest discover -s tests -v

The current suite contains nine tests covering:

• saving and loading memories
• empty-store behavior
• latest-memory retrieval
• complete history retrieval
• deterministic keyword search
• extended structured-memory persistence
• deterministic ranked retrieval
• filtering by memory fields
• filtered latest-memory retrieval

Design Principles

Deterministic Persistence

Important continuity information should not depend entirely on whether an LLM reconstructs previous context correctly.

Separation of Responsibilities

The persistence layer remembers stored information.

The language model reasons about it.

Inspectable Local Storage

JSONL keeps the implementation portable, human-readable, and easy to debug.

A developer can inspect the continuity store without specialized database tooling.

Deterministic Retrieval First

Version 0.2 improves retrieval without introducing embeddings or vector databases.

This keeps behavior understandable and inspectable while the architecture is still evolving.

Small Before Sophisticated

Continuity Engine intentionally avoids unnecessary infrastructure in its early versions.

The goal is to establish a reliable continuity layer before adding more advanced retrieval systems.

Relationship to Echo

Continuity Engine originated while developing Echo, a local AI assistant.

Echo needed reliable continuity between separate conversations. Rather than keeping the architecture tied to one application, the reusable persistence and retrieval concepts were extracted into this standalone project.

Version 0.2 expands the standalone engine using retrieval and structured-memory concepts validated inside Echo.

The long-term architecture is:

Continuity Engine
        ^
        |
       Echo

Echo becomes an application built on Continuity Engine rather than maintaining a separate duplicate continuity implementation.

This public repository contains no private Echo conversations, identity files, personal memories, credentials, secrets, or application-specific user data.

Roadmap

Near-term work includes:

• completing Echo integration
• retiring duplicate Echo continuity logic
• improving filtering and ranking where useful
• expanding test coverage

Future versions may explore:

• duplicate detection
• configurable ranking strategies
• richer session-level data models
• structured session summaries
• semantic retrieval
• pluggable storage backends
• REST API
• PyPI distribution
• integration examples for local and hosted LLMs

Status

Continuity Engine v0.2 is an early-stage but independently runnable and tested continuity library.

It is not yet intended to be a production-ready memory framework.

Development

This project uses an AI-assisted development workflow.

AI tools have been used for implementation support, debugging, code review, and iteration. The project is also being used as a hands-on study of persistence, retrieval, Python architecture, testing, and AI application design.

License

MIT License. See LICENSE for details.