Memory Governance

Agent Brain is designed for long-lived memory. Without maintenance, the store will accumulate:

• Duplicates
• Outdated decisions
• Contradictions

Governance keeps memory accurate and useful over time. The audit system is the primary tool for this.

Audit scopes

The brain MCP tool accepts an audit command with a scope parameter that controls what gets analyzed:

Recommended use:

• Run project audits regularly
• Run global audits when recall quality starts degrading
• Run cross audits before major releases or when onboarding a new agent

Finding types

Audit results include one or more findings, each with a type:

Running an audit

Via MCP

{
  "name": "brain",
  "arguments": {
    "command": "audit",
    "input": { "scope": "project", "project_id": "my-app" }
  }
}

Via REST

curl -X POST http://localhost:9090/api/v1/memories/audit \
  -H 'Content-Type: application/json' \
  -d '{"scope": "project", "project_id": "my-app"}'

For a global audit:

curl -X POST http://localhost:9090/api/v1/memories/audit \
  -H 'Content-Type: application/json' \
  -d '{"scope": "global"}'

The response includes:

• Memory IDs
• Finding types
• Human-readable descriptions

Review findings before taking action. The audit surfaces issues but does not modify memories automatically.

Suppressing a finding

Some flagged conflicts are intentional. For example, two projects may deliberately use different auth patterns, which an audit would flag as a conflict. Suppress the finding by storing an audit_suppression memory:

{
  "name": "brain",
  "arguments": {
    "command": "remember",
    "input": {
      "content": "Suppressing conflict finding for memory abc123 — the difference between my-app and legacy-app auth patterns is intentional. my-app uses short-lived JWTs; legacy-app uses session cookies for backwards compatibility.",
      "type": "fact",
      "tags": ["audit_suppression", "abc123"]
    }
  }
}

On the next audit run:

• Findings referencing abc123 will be skipped
• The suppression record remains part of the audit trail

Use this sparingly. Too many suppressions weaken the value of audits.

Merging duplicate memories

When an audit returns a redundancy finding, merge the duplicates via REST:

curl -X POST http://localhost:9090/api/v1/memories/audit/merge \
  -H 'Content-Type: application/json' \
  -d '{"memory_ids": ["uuid-1", "uuid-2"]}'

The merge operation:

• Combines the content into one record
• Preserves the union of tags
• Archives the source records

Review the merged result with the get_by_id command to confirm it is coherent.

Importing existing memories

Use the desktop app's Import wizard (Settings → Import) to seed Agent Brain from existing Claude, Gemini, Codex, or Aider memory files. The wizard accepts JSON, YAML, Markdown, and plain text, and shows a preview before committing.

For scripted imports, use the brain MCP tool:

• import — import a structured brainpack or JSON export
• import_foreign — import unstructured memory files from other agents (Claude memory JSONs, Aider chat history, etc.)

Both tools support dry_run: true so you can:

• Preview the import
• Validate the source data
• Avoid unintended writes

Recommended cadence

To keep audits manageable:

• Set a recurring reminder or schedule
• Review findings while they are still fresh
• Avoid letting multiple audit cycles pile up