Memory architecture

Castellan memory is the coordination substrate plus durable episode artifacts — not a vector store or conversation archive.

Layers

Layer	What	Where
Hot	Blackboard, `PheromoneField`, scheduler	In-process
Warm	Episodes, traces, checkpoints, topology archive	`.castellan/` JSON or SQLite
Cold	Turso Sync (planned)	Multi-machine share

flowchart TB
    subgraph hot["Hot"]
        BB[Blackboard]
        FIELD[PheromoneField]
        SCHED[Scheduler]
    end

    subgraph warm["Warm"]
        EP[episodes]
        TR[traces]
        TA[topology archive]
    end

    RUN[castellan run] --> SCHED
    SCHED --> FIELD
    RUN --> BB
    RUN --> EP
    RUN --> TR
    EVOLVE[castellan evolve] --> EP
    EVOLVE --> TA
    MCP[castellan mcp] --> warm
    REPLAY[castellan replay] --> EP

    classDef runtime stroke:#0969da,stroke-width:2px
    classDef substrate stroke:#8250df,stroke-width:2px
    classDef evolve stroke:#d97706,stroke-width:2px

    class RUN,REPLAY runtime
    class BB,FIELD,SCHED,MCP substrate
    class EVOLVE,EP,TR,TA evolve

Compared to vector-RAG systems: Castellan memory is environment-mediated — typed slots and zone signals, not embedding similarity. See Coordination model.

Today (JSON default)

castellan run --goal "reach target" --plugin gridworld
castellan replay --episode .castellan/episodes/<id>.json
castellan memory status

Artifact	Path
Episodes	`.castellan/episodes/<goal-id>.json`
Traces	`.castellan/traces/<goal-id>.jsonl`
Topology archive	`.castellan/topology_archive.json`

Live episodes: castellan_read_blackboard, castellan_deposit_signal — MCP tools.

SQLite backend

Set [memory] backend = "sqlite" in castellan.toml:

castellan_recall — query episodes, checkpoints, observations
castellan_remember — persist agent observations (not live field deposits)
castellan_query_field_history — sparse field snapshots at checkpoints

castellan evolve reads SQL aggregates when backend is sqlite. Full config: castellan.toml.

What never goes in the database

Data	Why
Live pheromone ticks	In-process decay semantics
Conversation transcripts	Anti-coordination — see Coordination model
Vector embeddings	Out of scope v1

Engineering detail

SQL schema, MemoryStore trait, sync policy: MEMORY_ARCHITECTURE.md (maintainer spec).