Memory

Every agent in Axocoatl has access to a four-tier memory system, hot to cold:

| Tier | Lives in | Latency | Used for | |------|----------|---------|----------| | 1 — Session | In-process state | µs | Current conversation, current turn | | 2 — Checkpoint | Disk (durable) | ms | Survives restarts; replay on crash | | 3 — Long-term | Disk (key/value) | ms | Cross-session facts the agent learned | | 4 — Semantic | Neural embeddings + cosine search | tens of ms | Retrieve by meaning, not by key |

All four tiers are local-first. None call out unless you configure them to (e.g. swapping in a remote vector DB for Tier 4).

Tier 4: neural embeddings

Tier 4 is backed by all-MiniLM-L6-v2 — a 384-dimension BERT model that runs via Candle, pure-Rust, no ONNX, no C++ runtime. The model auto-downloads the first time an agent asks for a semantic retrieval, then caches under {data_dir}/models/.

When you store a memory:

agent.memory_4.store("Customer reported the API hangs on >50MB uploads.")
              .await?;

The store embeds the text into a 384-dim vector and writes it to disk.

When you retrieve:

let hits = agent.memory_4.search("uploads stalling", top_k=5).await?;

The query is embedded, cosine-similarity is computed against every stored vector, top-k by score returns. Real recall — semantically related text with no shared words still scores high.

Embed-or-hash

If you build with --no-default-features (omitting neural-embeddings), Tier 4 falls back to a pure-Rust feature-hashing embedder. Recall is weaker but the binary stays tiny and there’s no model download. The store records which embedder produced its vectors and automatically re-embeds on a model change.

Checkpoints

Tier 2 is the checkpoint — a periodic disk snapshot of the agent’s message history, memory state, and pending mailbox. The supervisor uses it to restore an agent after a crash. You can also fork a session from a checkpoint via the dashboard’s time travel UI: pick a point in history, fork it into a new session, see how a different choice plays out.

Where the data lives

By default, under ./data/:

data/
  memory/
    session-{uuid}/
    checkpoints/
    long-term/
    semantic/
  models/
    all-MiniLM-L6-v2/

The data/ directory is gitignored by default. Move it to your home, back it up, sync it with Syncthing — your call.