Memory and RAG

Four different problems, not one memory bucket

That separation matters because each layer has different latency, size, persistence, and retrieval behavior. If you mix them conceptually, the architecture becomes fuzzy very quickly. The code does not treat them as the same thing, and the docs should not either.

1. The full session is durable even when the prompt is not

The first layer is the session store. Seshat persists multi-turn sessions so they can survive restarts, be resumed later, and remain inspectable. This is the source of truth for full transcript history. It is not constrained by the provider context window in the same way the active prompt is.

seshat sessions list
seshat chat --resume <session-id>
seshat chat --continue

This is the first distinction many agent systems blur. The model only sees the active request window. The runtime still owns a larger durable session record containing messages, metadata, tool results, and resumability information.

2. Compaction protects the active working window

The compaction engine in internal/runtime/memory estimates request tokens, computes an effective context window after reserving summary output budget, and triggers auto-compaction once the configured threshold is crossed. It first tries micro-compaction, then escalates to summary compaction if the context is still too large.

• AutoCompactThreshold is converted into an absolute token ceiling based on the current model window.
• CompactTargetPercentage defines how far the runtime tries to shrink the active context after compaction.
• MaxSummaryTokens reserves output space for the summarizer so compaction does not immediately recreate the same overflow.
• A consecutive-failure limit acts like a circuit breaker so a broken summarizer does not trap the session in endless retries.

The key point is architectural, not cosmetic: compaction reduces the provider-facing working set, but it does not mean the earlier session history disappeared from the runtime.

3. Durable learned memory is prompt support, not transcript storage

Separate from the transcript and compactor, the memory manager keeps scoped memory under <runtime-root>/memory. Its job is to surface stable context that should keep influencing future turns or future sessions.

The runtime also learns some of this automatically. User messages can be scanned for durable directives, tool usage can update pattern memory, and finished sessions can generate summaries that later re-enter the prompt as compact context. In catalog mode, the integration layer can also search memory entries instead of only formatting them into prompt text.

4. Explicit long-term memory tools are a second durable surface

There is another persistent memory path in the runtime: the explicit memory_* tool family. These tools do not just append notes to the prompt. They operate on a long-term knowledge graph with entities, observations, search, and node opening.

memory_create_entities
memory_add_observations
memory_search_nodes
memory_open_nodes

rag_ingest
rag_search

In the CLI runtime, this graph is wired through LongTermMemory and backed by the same SQLite database path when available. This means Seshat currently has two durable-memory shapes: prompt-facing scoped memory for reuse in future prompts, and tool-facing graph memory for explicit structured recall.

5. RAG is retrieval from corpora, not memory of the session

The RAG service in internal/rag ingests text into a named corpus, chunks it, embeds each chunk, and upserts the records into a vector store. At query time it embeds the question, searches the corpus namespace, optionally blends keyword scoring through HybridWeight, and can apply a reranker before returning the final results.

• The default chunker is local and simple: paragraph splitting with a hard cap around 800 characters per chunk.
• The default embedded vector backend is the persistent HNSW store under <runtime-root>/data/hnsw.
• Artifact storage is optional, so the index can still work even when raw document blobs are not persisted.
• The CLI only enables RAG automatically when an embedding endpoint is configured.

export RAG_EMBEDDING_URL=http://localhost:11434
export RAG_EMBEDDING_MODEL=nomic-embed-text
export RAG_EMBEDDING_PROVIDER=ollama

seshat chat

SDK wiring keeps the distinction explicit

The SDK composition boundary makes the architecture obvious. Memory, RAG, and long-term graph memory are not one field or one switch. They are separate capabilities wired into the client and then exposed through the runtime.

client, err := sdk.NewClient(&sdk.ClientConfig{
    EnableMemory:   true,
    RAGService:     ragSvc,
    LongTermMemory: graphStore,
})

Memory is not RAG

Good systems usually need both. Memory helps the runtime stay coherent over time. RAG helps it pull in source material that is too large or too external to live inside that memory permanently.

What exists today versus what is still evolving

Next concept

Once memory boundaries are clear, the next important layer is capability distribution: how tools, skills, and MCP servers extend the runtime without breaking its core contract.