Memory

Learned memory is a short list of facts that the Agent keeps for a Session. Each fact has a source in the conversation. OpenBot adds facts after each Turn and shows them to the model in later Turns. You can also add, remove and turn off facts yourself. This page shows how learned memory works and how to change it with the API.

Learned memory belongs to one Session. It is part of the Session’s history, so a Fork takes a copy of it. Other Sessions do not see it.

Each Agent also has a long-term memory over all its Sessions. See Agent memory.

---

Read memory

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  https://api.example.com/v1/sessions/$SESSION/memory

{
  "entries": {
    "budget": {
      "key": "budget",
      "content": "The trip budget is 1500 EUR.",
      "kind": "fact",
      "sources": ["i-02"],
      "updatedAt": 1792486800000,
      "status": "active"
    }
  },
  "processed": ["i-01", "i-02"],
  "settings": { "use": true, "generate": false },
  "overrides": { "generate": false }
}

Field	Meaning
key	A stable name for the fact. One key holds one fact.
content	The fact in plain text.
kind	fact, decision, preference, procedure or hypothesis.
sources	The IDs of the Items that support the fact.
status	active, or retracted when the fact was removed.
processed	The Items that OpenBot has already read for memory.
settings	The switches in use for this Session. See below.
overrides	The switches that this Session sets itself.

---

Switches

Two switches control memory:

• use: OpenBot adds the active facts to the model’s instructions.
• generate: OpenBot learns new facts after each Turn.

The organization sets a default for each switch with memory in its settings. Both are on unless the organization changes them. A Session can override each switch with Configure. A switch that the Session does not set follows the organization default. settings shows the result, and overrides shows what the Session set. A Fork keeps the overrides of its source Session.

---

How OpenBot uses memory

In a Turn

When use is on, OpenBot adds the active facts to the model’s instructions when the Turn runs. The text tells the model that memory is past evidence and that current instructions win. Retracted facts are not sent.

The memory text has a size limit of 8000 characters. The newest facts come first. OpenBot stops before the first fact that does not fit, so older facts are left out. A fact is never cut in the middle. To change the limit, give your own policy on the server: sessions.memory.policy: MemoryRules.make({ maxLength: 4000 }).

After a Turn

When a Turn completes, OpenBot consolidates memory. To consolidate means to read the new Items and update the list of facts. This also happens when a Turn completes after an approval. OpenBot asks the Turn’s model to find facts worth keeping. The model must name the source Items for each change. OpenBot applies the changes to the newest memory. So an edit that you make while the model works is kept. A Turn that only runs an App action does not change memory, because no model runs in it.

OpenBot checks these rules for every change:

• OpenBot reads only Items that it has not processed yet.
• Each change must name at least one of those Items as its source.
• One change per key. A retracted fact stays retracted. Only a direct Remember can bring it back.

OpenBot also tells the model to reuse a key for the same fact, to count only clear user statements as preferences, and to never keep passwords, keys or links that give access.

If the model fails, the Turn still completes. OpenBot records the error and tries again with the next Turn. Turn generate off to stop this step.

---

Change memory

All changes use one route: POST /v1/sessions/:sessionId/memory.

{
  "expected": "v-7d21",
  "revision": 5,
  "command": {
    "_tag": "Remember",
    "key": "budget",
    "content": "The trip budget is 1500 EUR.",
    "kind": "fact"
  }
}

Field	Meaning
expected	The Timeline head you last saw: session.head from the Session view.
revision	The Session revision you last saw: session.revision.
command	What to do. See the commands below.

If the Session or its history changed since you read it, OpenBot returns 409 with SessionConflict. Read the Session again and retry. On success, OpenBot returns the new Session view. It has a new session.revision. Remember and Forget also make a new session.head.

Commands

_tag	Fields	What it does
Remember	key, content, kind	Adds a fact, or replaces the fact with this key. It makes the fact active.
Forget	key	Marks the fact as retracted. An unknown key returns 409.
Configure	use, generate (both optional)	Sets the switches of this Session. See below.
Refresh	none	Runs consolidation now with the Session’s model.

For each field of Configure:

• true or false sets the switch for this Session.
• null removes the setting. The switch then follows the organization default.
• A missing field keeps the switch as it is.

Configure does not change the history, so session.head stays the same.

Remember and Forget also add a small Item to the history that records your edit. This Item becomes the source of the change.

Examples

Forget a fact:

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":"v-8e02","revision":6,"command":{"_tag":"Forget","key":"budget"}}' \
  https://api.example.com/v1/sessions/$SESSION/memory

Keep using the facts, but stop learning new ones:

{
  "expected": "v-9f13",
  "revision": 7,
  "command": { "_tag": "Configure", "generate": false }
}

Follow the organization default for learning again:

{
  "expected": "v-9f13",
  "revision": 8,
  "command": { "_tag": "Configure", "generate": null }
}

Learn from the history now:

{ "expected": "v-9f13", "revision": 9, "command": { "_tag": "Refresh" } }

Note

Refresh does nothing when generate is off. Otherwise it needs a model. If OpenBot has no model, it returns 409 with SessionConflict. Refresh does not check expected and revision, but you must still send them.

See all fields in the Sessions reference.

---

Agent memory

Agent memory is what one Agent learns over many Sessions. It keeps only lasting experience:

Kind	Example
procedure	“Run the tests before you report that work is done.”
preference	“Ana likes short answers with a list of changes.”
decision	“The team uses Effect for all new services.”

Facts that matter for one task only stay in Session memory.

How it learns

When a Turn of the Agent completes and its queue is empty, OpenBot asks the helper model which lasting experience to keep. The helper model is helperModel in the organization settings. To stop this learning, set agentMemory to false there. Review Sessions do not teach anything. A Session whose generate switch is off does not teach its Agent either.

• Each entry names its sources: Session and Item IDs.
• Tool results from Apps are outside data. An entry that only App results support is never kept.
• The Agent always knows which person it works with. The memory model also knows it, so entries can say who said what.
• Retracted entries stay retracted. Only a person can bring one back.

Agent memory does not follow a Timeline. A Fork never changes it, and going back to an old Version does not undo it. To remove an entry, forget it.

OpenBot adds the active entries to the instructions of every Turn of the Agent, newest first, up to 8000 characters. The text says that current instructions win over memory.

Shared Agents

A shared Agent has one memory for every member who uses it. The Agent decides what to share: it gets fixed rules about privacy in every Turn. What it learned from one person may be private, so it tells another person only what is clearly shared work.

Read and change it

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  https://api.example.com/v1/agents/$AGENT/memory

{
  "entries": {
    "tests-first": {
      "key": "tests-first",
      "content": "Run the tests before you report that work is done.",
      "kind": "procedure",
      "sources": [{ "session": "c81d…", "item": "i-12" }],
      "updatedAt": 1792486800000,
      "status": "active"
    }
  },
  "version": 4
}

Change it with a Remember or Forget command. expected is the current version:

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":4,"command":{"_tag":"Forget","key":"tests-first"}}' \
  https://api.example.com/v1/agents/$AGENT/memory

GET /v1/agents/:agentId/memory/log lists each change with its version, the time, what made it (consolidation, person or promotion), and the changed keys.

When you promote a subagent, the lasting entries of its Session memory become its Agent memory.