Agent memory

Engram, the workspace's experiential memory — capture and recall lessons from the CLI, the OBSERVATION → RULE → FACT confidence ladder, and how memory is distinct from the knowledge graph.

As the agent works, it learns things: that a test is flaky for a specific reason, that your team always uses withTenantDb, that the staging database is on an unusual port. Agent memory — powered by Oxagen's memory engine, Engram — is where those lessons live. Before starting new work the agent recalls the relevant ones, so it doesn't re-discover the same gotcha twice. This is the flywheel that makes the agent get better in your workspace over time.

Memory is workspace-scoped: shared across every session, one-shot run, and fleet subagent in the workspace — not per-conversation, and never leaked across workspaces or organizations.

Memory is not the knowledge graph. Agent memory is experiential — what the agent learned from doing work. The knowledge graph is structural — what your code and entities are. The agent engine draws on both: memory tells it what worked last time, the graph tells it how the system is wired.

The two axes

Every memory has two independent axes, so "how sure are we it's true" is kept separate from "what is it about":

Class — the epistemic ladder, from tentative to settled: OBSERVATION → RULE → FACT.
- OBSERVATION — something noticed in passing.
- RULE — a distilled instruction the agent should follow, with an enforcement strength.
- FACT — settled ground truth (promotion to FACT requires human confirmation).
Kind — the content domain, an open label like gotcha, convention-deviation, bug-root-cause, preference, or constraint.

And two independent scores:

Confidence (0–100) — how sure the memory is true. It decays over time and recovers when re-confirmed.
Enforcement (1–100, RULE only) — how strongly it should be followed.

Frequently-cited, outcome-positive memories resist decay; unused ones fade and are archived (recoverable, not deleted). Citations create the pressure that surfaces promotion candidates — the self-improvement loop.

Capture a memory

From the REPL, /remember infers the class and kind from your text:

› /remember always use withTenantDb, never raw db()
◇ saved RULE · gotcha

Or from the shell, with oxagen remember — pin the class and enforcement when you want to:

oxagen remember "the staging DB listens on port 5433"
oxagen remember "always use withTenantDb, never raw db()" --class RULE --enforcement 90

Flag	Purpose
`--class <OBSERVATION\|RULE\|FACT>`	Pin the epistemic class instead of inferring it.
`--kind <kind>`	Pin the content-domain kind.
`--enforcement <1-100>`	How strongly to follow it (RULE only).
`--node <ref>`	Anchor the memory to a graph node.
`--json`	Machine-readable output.

Browse and recall

› /memories             # recent memories
› /memories RULE        # only rules
› /memories deploys     # filter by kind/text
› /forget mem_01H…      # delete one by id

The full management surface is oxagen memory:

oxagen memory list --class RULE --sort citations   # rules, most-cited first
oxagen memory show mem_01H…                         # one memory in full
oxagen memory edit mem_01H… --lesson "…"            # revise (re-embeds)
oxagen memory candidates                            # observations ripe to promote
oxagen memory rm mem_01H…                           # delete

Promote up the ladder

When an observation has proven itself, promote it — this records an auditable event:

oxagen memory promote mem_01H… --to rule --enforcement 80 \
  --rationale "cited in three reviews; team agreed to enforce"

--to fact requires human confirmation. oxagen memory salience adjusts confidence, enforcement, or lifecycle status (ACTIVE/SUPERSEDED/RETRACTED/ARCHIVED) without changing the class.

Import existing docs

Turn a folder of Markdown convention/rule docs into memories in bulk:

oxagen memory import docs/conventions/*.md          # preview
oxagen memory import docs/conventions/*.md --yes     # commit

How the agent uses memory automatically

You rarely call these by hand mid-task. During the enhance stage the agent recalls relevant memories semantically and folds them into context; when a turn had to be corrected, the pipeline records a gotcha memory so the next run avoids the same mistake. RULE-class memories with high enforcement are surfaced as instructions the worker must honor.

Governance

Memory writes are governed by the same IAM model as every capability and produce an audit record — including both the human principal and the agent when written in delegated context. Because memory lives in the workspace graph, it is portable: a workspace's memories travel with the workspace, not locked to Oxagen's storage.

Knowledge graph — the structural context memory sits alongside.
The agent engine — where recall and gotcha-writing happen in the turn.
In-app agent memory — the same memory, viewed and managed from the web app.

Agent memory

On this page