OpenLoop / Memory

How OpenLoop remembers

There isn't one memory, there are a few, each with a different job. This page maps them so it's clear what holds what, how long it lasts, and which one makes OpenLoop remember across months of use.

living document

The shape of it

Think in three timescales. The model's attention holds the current moment, a run log holds one task end to end, and the durable stores hold everything worth carrying forward.

Always on
Identity (persona)
Who the agent is, and who it is talking to. SOUL.md (the stable self) is prepended to every prompt; USER.md (its model of you) rides alongside and is re-read constantly. The frame around everything below.
Short term
Context window
The live turn the model is reasoning over. Compacted to a summary when a session runs long, so nothing falls off a cliff.
Per run
Run event log
One task, recorded as an ordered stream: the plan, each agent dispatched, every tool call and result. Replayable, so any surface can rebuild the exact state.
Long term
Durable stores
What survives across sessions: learned episodes, hand-curated facts, and the structure of each codebase. This is the layer that lets it improve over time.

The layers

Context window

live

The working memory of a single session.

Holds
The current conversation and tool output
Lifespan
One session; compacted when long
Lives in
The model
Recalled
Inherent (it is the prompt)

Run event log

live

A replayable record of one task, start to finish.

Holds
Plan, dispatches, tool calls, results, artifacts
Lifespan
The run (kept for replay)
Lives in
The assistant's merged stream
Recalled
Replay by sequence number

Semantic memory

building

Auto-captured episodes, recalled by meaning. The long-term brain.

Holds
What worked, decisions, outcomes, gotchas
Lifespan
Forever, until it decays as stale
Lives in
A vector + keyword index in the core
Recalled
Hybrid search, injected at session start

Operator memory

live

Hand-curated facts about you and your projects.

Holds
Preferences, goals, project state, decisions
Lifespan
Persistent, human-curated
Lives in
Markdown files (an index plus notes)
Recalled
Loaded into context each session

Codebase memory

live

The structure of a repo, queryable instead of re-read.

Holds
Call graphs, architecture, decision records
Lifespan
Per repo, refreshed on index
Lives in
A local graph (its own tool)
Recalled
Tool calls (trace a path, get the map)

Identity / persona

live

Who the agent is, plus its model of you. The Hermes three-tier pattern.

Holds
SOUL.md (stable self) and USER.md (operator model)
Lifespan
SOUL rarely changes; USER deepens over time
Lives in
~/.nyx/persona
Recalled
Prepended to every prompt (not searched)

One thing often gets called memory but isn't: the secrets vault. That's configuration (keys and settings), not recall. It is deliberately kept separate.

How it remembers over long use

The durable improvement comes from one loop running quietly under every task. Capture is cheap and never blocks the work; recall happens up front so the agent starts a task already knowing what it learned last time.

Capture
As an agent works, its interactions and outcomes are written as episodes. Bounded and async, so it never slows or breaks the run.
Consolidate
Episodes settle into tiers; stale, low-signal ones decay so the store stays sharp instead of bloated.
Recall
On a new task, a hybrid keyword-plus-meaning search pulls the few most relevant past episodes.
Inject
Those are placed into the prompt under a strict token budget, so the agent benefits without drowning in history.

The standard going forward

Three durable layers, one job each

The confusion was having several stores with no clear division. The standard is simple: an always-on identity frame, three long-term recall layers that do not overlap, and the two short-lived ones above them.

  • Identity (SOUL.md + USER.md) is the always-on frame, not recall: the agent's stable self and its model of you, prepended to every prompt (the Hermes pattern). It lives in the concierge today and needs to carry into the assistant.
  • Semantic memory is the canonical cross-session brain. Everything an agent learns by doing flows here automatically and comes back by meaning. This is what "remember over long use" means.
  • Operator memory stays the human layer: the curated, readable facts you want guaranteed in context, not left to similarity search.
  • Codebase memory stays the code layer: structural truth about a repo, queried on demand rather than recalled by vibe.

Short-term context and the per-run log sit on top and feed the durable layers. Nothing else should call itself memory.