EKOSdocs
Docs / Guides Build

Agent Session Memory

Let an agent leave anchored notes for its next session, with staleness detection, without ever writing the ledger itself.

Session memory (RFC 0151) lets an agent record a decision and its why, a dead end or a constraint, tied to real objects in your compiled ledger. At the next session EKOS tells it whether the thing a note describes has changed since.

The feature is opt-in and never a source of truth. Every note is an unconfirmed agent claim (tier T0) until a person confirms it. Notes never appear in ekos ask, ekos query, ekos_search, ekos_retrieve, EKL or the graph tools. They are only returned by the session tools, and always with their tier and staleness verdict.

Turn it on

[session-memory]
enabled = true
# defaults: max-note-chars = 2000, max-entries-per-session = 200, max-bytes-per-session = 262144,
#           capture-retention-days = 14, extraction = false, inbox-dir = ".ekos/session/inbox"

The loop

ekos session note "orders.total is stored in cents" --kind decision \
    --rationale "finance reports dollars" --anchor orders    # inbox file only; no ledger write
ekos session status                                          # counts, dropped, pending
ekos session commit                                          # inbox → unconfirmed, anchored claims
ekos session recall "how is orders total stored"             # tier + staleness verdict per hit
ekos session brief --scope orders --budget 800               # token-budgeted brief for a new session
ekos session review <claim-id> confirm                       # HUMAN ONLY: T0 → T1

Note kinds: finding, decision, dead_end, constraint, todo. An anchor must be an exact object name or a workspace-relative path. An ambiguous or unknown anchor is recorded as such and never guessed. --scope (or --scope-from-git) ranks notes about what you are editing first.

Staleness

Each anchor stores a fingerprint of the narrow slice of state its note is about: a table's columns, a symbol's signature or a section's text. At read time each note gets one of four verdicts:

Verdict Meaning
fresh the anchored state is unchanged
changed it changed; the brief marks the line [CHANGED] and says what changed
orphaned the anchor left the ledger ([ORPHANED])
unanchored the note has no anchor

A confirmed note whose anchor changes still shows changed. Confirmation does not freeze the code.

Over MCP

Tool Access
ekos_session_note writes only the inbox file; it opens no ledger handle
ekos_session_recall read
ekos_session_brief read

No MCP tool can confirm, reject or supersede a note. Recalled text is wrapped in a <session-memory untrusted="true"> envelope, and the instructions sit outside that envelope.

Safety

  • Secrets are redacted when a note is written and again at commit. If redaction fails, the note is dropped.
  • Inbox files are created 0600 and the inbox directory 0700. Anchors or inbox paths that point outside the workspace are refused.
  • Nothing is deleted from the ledger. Superseded or rejected notes simply drop out of default ranking. ekos session purge deletes inbox files and transcript slices, but claims that were already committed remain, and their evidence then reads "source purged".
  • Residual risk: redaction is pattern-based, and the ledger is append-only.

Optional extras

ekos session capture stores redacted transcript slices outside the ledger. ekos session extract (needs extraction = true) asks the [llm] provider for claim proposals. A proposal must quote a span that exists in its slice or it is dropped, and every proposal is still only T0. With a cloud provider, extraction is a metered call.

Measured so far: in a live comparison against a model-written compaction summary at 7 notes, session memory showed no correctness advantage, and the staleness difference was inconclusive. Whether it helps at larger volumes is untested.