Agent Memory

Overview

Agent memory gives every agent that touches your workspace a persistent, queryable record of what it has done — and what went wrong. Actions are captured automatically, grouped into sequences, and promoted into patterns that are injected back into the agent's context before each run. The result is an agent that learns from the graph over time without any manual prompting or bespoke RAG plumbing.

Memory is per-workspace, workspace-scoped (RLS-enforced), and accessible through the same MCP tools and REST API that govern the rest of the ontology graph.

Agent memory is one of four memory layers in a workspace. For the overall model — semantic, episodic, telemetry, and the working set — and how they interact during a chat turn, see Workspace Memory.

How it works

Agent memory has three layers, each building on the one below:

The flow end to end:

Agent action
    │
    ▼
_mem:action written to Neo4j + Postgres
    │
    ▼  (Pass 1 — triggered per action)
_mem:sequence — actions grouped by session_id within 5-min window
    │
    ▼  (Pass 2 — every 15 min)
_mem:pattern — promoted when threshold met; confidence updated
    │
    ▼  (pre-execution hook — before each action)
Relevant patterns injected into agent system prompt
    │
    ▼  (Pass 3 — nightly)
_mem:benchmark — metric values written; delta_vs_baseline computed

All _mem:* nodes live in the same Neo4j workspace graph as your domain nodes. Any _mem:references edge connects a memory node to the workspace entity it touched, so you can traverse from any node to its full agent history in one hop.

Enabling agent memory

Via the app

1. Open your workspace in the Oxagen dashboard.
2. Go to Settings → Agent Memory.
3. Toggle Enable agent memory on.

Memory capture begins immediately for all subsequent agent actions.

Via MCP

From any connected coding agent:

workspace.enable_memory

No arguments needed — the server derives your workspace from the bearer token. To disable:

workspace.disable_memory

Pre-execution context injection

When agent memory is enabled, Oxagen automatically injects a structured "past experience" block into the agent's system prompt before each action. The block contains patterns that:

• Reference one or more of the target nodes for the pending action, and
• Have confidence_score ≥ 0.6, or
• Have been manually annotated by a workspace operator

Example injected block:

[Oxagen memory — 2 relevant patterns]

Pattern: ontology_mutation:person:NodeNotFoundError (confidence 0.83)
Recommendation: 83% of ontology_mutation actions on person nodes fail
with NodeNotFoundError. Validate the node exists and is accessible
before proceeding.

Pattern: graph_query:email:None (confidence 0.71)
Recommendation: 71% of graph_query actions on email nodes succeed.

No configuration required. The hook runs for every action once memory is enabled. To opt out for a specific workspace, toggle off context injection in Settings → Agent Memory → Pre-execution injection.

Custom evaluation metrics

Oxagen ships three built-in metrics that activate automatically for every workspace with memory enabled:

These give you the headline "is memory helping?" number. Built-in metrics can be disabled but not deleted.

Defining a custom metric

Custom metrics let you measure what "better" means for your specific workflow.

Via MCP:

{
  "tool": "memory.metric_create",
  "name": "Schema merge success rate",
  "event_filter": {
    "action_type": ["ontology_mutation"]
  },
  "success_condition": "outcome == 'success'",
  "aggregation": "rate",
  "window_days": 14,
  "description": "Rate of successful schema mutations over the last 14 days"
}

Via the app:

1. Go to Workspace → Agent Memory → Metrics.
2. Click New metric.
3. Fill in name, event filter, success condition, aggregation, and window.
4. The live preview shows what the metric would return against your existing data before you save.

Metric fields

Updating and deleting metrics

{ "tool": "memory.metric_update", "metric_id": "<uuid>", "window_days": 30 }

{ "tool": "memory.metric_delete", "metric_id": "<uuid>" }

Built-in metrics are deactivated (not deleted) to preserve benchmark history.

Viewing agent memory

Timeline view

Workspace → Agent Memory → Timeline

Chronological list of all _mem:action and _mem:sequence nodes. Filterable by agent_id, action_type, outcome, and date range.

Pattern list

Workspace → Agent Memory → Patterns

All promoted patterns, sortable by confidence, sample count, and last seen date. Use this view to:

• Suppress patterns that are no longer valid (see Pattern management)
• Add operator annotations that get injected regardless of confidence threshold

Memory ROI panel

Workspace → Agent Memory → Metrics

Per-metric benchmark trend charts. The headline number is delta_vs_baseline — the difference between the metric's current value and the value computed from the workspace's first 50 sequences.

delta_vs_baseline = current_value - baseline_value

A positive delta means the agent is performing better than when memory was first enabled. A negative delta means performance has degraded — check the pattern list for suppressed or misleading patterns.

MCP tools reference

All tools derive workspace_id from the bearer token — never pass it as an argument.

Pattern management

Suppressing a pattern

If a pattern is producing incorrect recommendations, suppress it:

{
  "tool": "memory.annotate",
  "pattern_id": "<uuid>",
  "suppressed": true,
  "annotation": "This pattern was triggered by a one-off migration, not normal agent behavior."
}

Suppressed patterns remain in the database for audit purposes but are not injected into agent context. They still appear in the pattern list with a suppressed badge.

Adding an operator annotation

Annotations let you override or augment the system-generated recommendation:

{
  "tool": "memory.annotate",
  "pattern_id": "<uuid>",
  "annotation": "Always call ontology.get_node before mutating a person node in this workspace."
}

Annotated patterns are injected regardless of confidence threshold.

Pattern lifecycle

• Promoted when ≥ 5 sequences + ≥ 60% same outcome
• Updated in place when new sequences reinforce the same key
• Superseded (new node written, _mem:supersedes edge created) when confidence shifts ± 15%
• Decayed at 10%/week when not reinforced for 30+ days
• Soft-deleted when confidence drops below 0.2

How the MCP server manages memory automatically

When your agent is connected via MCP, Oxagen handles the full memory lifecycle without any agent-side configuration:

1. Capture — every tool call (ontology.create_node, ontology.traverse, etc.) triggers the action capture hook. The action is written to Neo4j and Postgres before the result is returned to the agent.
2. Grouping — within 5 minutes of a session ending, Pass 1 groups the session's actions into a _mem:sequence and links them via _mem:contains edges.
3. Pattern detection — every 15 minutes, Pass 2 scans recent sequences and promotes patterns. Your agent's next run will see any newly promoted patterns.
4. Benchmarking — nightly, Pass 3 decays stale patterns and writes benchmark rows for all active metrics.
5. Injection — before each tool call, the pre-execution hook queries patterns referencing the target nodes and prepends the "past experience" block to the agent's system prompt.

The agent receives richer context on every subsequent run without any prompt engineering on your part.

Disabling memory

Per workspace

Via app: Settings → Agent Memory → toggle off.

Via MCP:

workspace.disable_memory

Disabling stops new action capture and pre-execution injection. Existing _mem:* nodes are preserved and remain queryable. Re-enabling resumes capture and picks up where it left off.

Data model

All _mem:* nodes live in the Neo4j workspace graph alongside your domain nodes. Postgres agent_memory schema holds the same data in row form for fast filtering, RLS scoping, and metric evaluation.

Cross-workspace memory is explicitly out of scope. Patterns never leave the workspace they were derived from.