Workspace Memory

Overview

Workspace memory is a simplified store of insights and knowledge scoped to a single workspace. Each memory lives in the ontology graph as a memory node.

There are two kinds:

Memories start as suggestions and can be promoted to facts when validated.

Lifecycle

Creating Memories

Memories start as suggestions via:

• POST /v1/workspaces/{workspace_id}/memories with kind: "memory"
• Command: /oxagen:remember "content"

Promoting to Facts

Important memories can be promoted to authoritative facts:

• POST /v1/workspaces/{workspace_id}/memories/{id}/promote
• Command: /oxagen:promote <memory-id>

Deleting

Both memories and facts can be removed:

• DELETE /v1/workspaces/{workspace_id}/memories/{id}
• Command: /oxagen:forget <memory-id>

Citation pattern

When the agent uses a memory in a response it cites it inline with [mem:<id>], where <id> is the memory node UUID. The chat surface renders citations as links back to the workspace memory page. The citation is the read-path signal: it is how times_referenced is incremented and how downstream tooling reconciles answers to source memories.

times_referenced

Every memory carries a times_referenced counter. The counter is incremented exactly once per agent run that emits a [mem:<id>] citation referencing it — the increment happens in the finish_run hook after the run reaches a terminal state, so it reflects shipped answers rather than draft tool calls.

times_referenced is the primary signal for:

• Pin recommendations — high-reference memories surface as candidates for the workspace memory page's pinned list.
• Stale culling — notes whose times_referenced stays at zero beyond the workspace retention window are eligible for purge.
• Weight adjustment — the weight_memory API takes a times_referenced-aware delta so manual weight changes do not fight the recall signal.

The counter is monotonic across the memory's lifetime; soft-deletes do not reset it.