Back to App
Memory

Overview

Design philosophy, 3-tier architecture (Server/Daemon/Runtime), 7 core memory types, and OKF directory mapping for Mopheus cross-ticket memory.

In complex software engineering and IT operations, AI agents should never be transient operators that forget everything once a ticket is closed. Mopheus builds an enterprise-grade long-term memory system founded on centralized persistence, deterministic scoped delivery, read-only projection, and continuous cognitive promotion.

When an agent resolves an intricate error, troubleshoots a toolchain incompatibility, formulates a multi-step SOP, or receives direct correction from a human expert, these insights are distilled into structured memory cards. When a new related task is created or claimed, the system uses multidimensional scoping and hybrid retrieval to inject proven prior knowledge into the agent's workspace—compounding team intelligence over time.

┌─────────────────────────────────────────────────────────────┐
│                   Mopheus Memory Lifecycle                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Ticket Completion / Runtime Telemetry                     │
│          │                                                  │
│          ▼                                                  │
│   Distillation ──────► Cognitive Promotion (Resolution→SOP) │
│          │                                                  │
│          ▼                                                  │
│   Centralized Store ───► PostgreSQL SSOT / Supersede Chain  │
│          │                                                  │
│          ▼                                                  │
│   Task Delivery ───────► ETag 304 / Cache Pool / Projection │
│          │                                                  │
│          ▼                                                  │
│   Runtime Sandbox ─────► MEMORY.md Index / Relative Links   │
│                                                             │
│   (Immutable Read-Only Projection Prevents Host Pollution)  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Core Design Principles

  1. Centralized Store as the Single Source of Truth (SSOT)
    All memory records are permanently stored in the centralized server PostgreSQL database. Agent sandboxes and container workspaces are ephemeral and disposable. Local sandbox files must never be treated as autonomous sources of truth. All additions, modifications, and deprecations must be executed through controlled APIs and the Mopheus CLI.

  2. Deterministic Scoped Delivery & Anti-Pollution
    The system never dumps memories into tasks indiscriminately. Delivery strictly separates the workspace global baseline from targeted entity scopes (such as target asset asset_id, tech stack db_type, or requester user_id). Asset-specific configurations are only delivered to tasks targeting that exact asset, completely preventing cross-asset pollution and token waste.

  3. Host Read-Only Projection & Strong Isolation
    At daemon runtime, memory cards are mirrored from a shared host Cache Pool. In Linux production environments, Bubblewrap mounts this pool as read-only via --ro-bind into .claude/memory/. In non-Linux environments, relative symbolic links are used. Any modifications attempted inside the sandbox fail or are discarded upon task exit, protecting the central knowledge base from corruption.

  4. Active Maintenance & Cognitive Promotion
    Memory is not a cluttered dump of raw logs. Mopheus encourages agents and engineers to refine transient error fixes (resolution) into reusable standard procedures (procedure), elevate proven practices into team conventions (preference), and explicitly deprecate outdated records via --supersedes.

3-Tier Architecture Overview

The Mopheus memory system spans three distinct tiers: Control & Storage, Host Node Transfer, and Task Execution Sandbox:

[Control & Storage Tier: Server & PostgreSQL]
  │ • Core tables: memory, memory_source, memory_distillation
  │ • Retrieval engine: multidimensional scoping + native weighted full-text search (content_tsv GIN index) + pg_trgm similarity
  │ • ETag calculation & task-specific MEMORY.md construction
  ▼
[Node Transfer Tier: Daemon & Host Cache Pool]
  │ • HTTP weak ETag negotiation (304 Not Modified support)
  │ • Host shared workspace Cache Pool (<cache_dir>/workspaces/<ws_id>/cards/)
  │ • Cross-process file locking (.lock) & atomic file swaps
  ▼
[Execution Sandbox Tier: Runtime Workspace]
  │ • Immutable read-only mount (.claude/memory/ via Bubblewrap --ro-bind)
  │ • Task-scoped index file (.claude/memory/MEMORY.md)
  │ • Relative Markdown links pointing to physical OKF cards

The 7 Core Memory Types & OKF Pillar Topology

Mopheus adopts the Open Knowledge Format (OKF) standard to organize cards into an intuitive, human-and-agent-readable directory hierarchy across four primary pillars: runbooks/, facts/, conventions/, and docs/.

The system supports 7 first-class memory types, mapped to the physical filesystem as follows:

OKF PillarPhysical DirectoryMemory Type (memory_type)Short AliasCore Semantics & ContentDelivery & Scoping Rule
runbooks/runbooks/errors/error_resolutionresolutionVerified troubleshooting steps for specific errors, exceptions, and exit codes.Triggered by error codes, text similarity, or keyword match.
runbooks/runbooks/pitfalls/failure_scenarioriskArchitectural pitfalls, known bugs, version incompatibilities, and warning signs.Injected on semantic similarity or matching stack profiles.
runbooks/runbooks/playbooks/success_playbookprocedureHigh-value SOPs formatted as 5-stage JSON (goals, preconditions, steps, validation, rollback).Matched by task type, operational intent, or workflow tags.
facts/facts/specs/environment_factfactStable infrastructure specifications, OS versions, baseline ports, and topologies.Scoped: Global baseline (asset_id IS NULL) is injected; asset-specific facts require matching asset_id.
conventions/conventions/corrections/human_correctioncorrectionExplicit corrections and guardrails provided by human engineers/DBAs.Highest Precedence. Overrides conflicting agent proposals.
conventions/conventions/preferences/preferencepreferenceTeam conventions, commit standards, operational windows, and requester habits.Global preferences apply workspace-wide; user preferences match requester user_id.
docs/docs/reference_docreference / docsStructural architectural guidelines, team playbooks, and contextual reference manuals.Recalled via semantic search or explicit category navigation.

[!IMPORTANT] Asset-Bound Scoping: Global Facts vs. Asset-Specific Facts
Environment facts in Mopheus are strictly bound to assets (asset_id) rather than injected globally:

  • L0 Workspace Global Facts (asset_id IS NULL): Universal environment baselines that apply across all workspace tasks.
  • L2 Asset-Specific Facts (asset_id = '<target>'): Configurations and parameters bound to a specific asset, delivered exclusively when a task targets that asset.

Enabling the Memory System

The memory system is gated by workspace and system-level feature flags.

To enable memory for a workspace:

# Enable the memory feature via Mopheus CLI
mop workspace feature enable --key memory

# Verify workspace feature status
mop workspace feature list

When enabled:

  • The system automatically triggers asynchronous distillation upon ticket completion.
  • When new tasks are scheduled, the daemon automatically queries memory candidates, builds MEMORY.md, and projects OKF cards into the execution sandbox.
  • Both human engineers and agents can use mop memory commands to search, inspect, create, and audit memories.

Guide Navigation

To explore the architecture and implementation in depth, read the following chapters:

  1. Storage, OKF Specification & Lifecycle — PostgreSQL single source of truth, YAML Frontmatter, 5-stage SOP schemas, version chains, and offline CLI workflows.
  2. Memory Delivery & MEMORY.md Construction — L0/L1/L2 tiered filtering, dynamic index generation, daemon ETag caching, Bubblewrap --ro-bind isolation, and agent interaction contracts.
  3. Multidimensional Scoping & Precise Retrieval — Isolation across assets, stacks, projects, and tags; native multi-language weighted full-text search; two-phase matching; and human-correction priority rules.
  4. Distillation, Cognitive Promotion & Skill Evolution — Distillation skills architecture (Core/General/Specialty), negative pattern guards, the promotion ladder, and compiling memories into native Mopheus Skills via mop memory synthesize-skill.

Files

Centrally manage and explore all files, reports, and data artifacts generated across workspace tickets, comments, and agent conversations.

Specification

In-depth exploration of PostgreSQL persistence, OKF YAML Frontmatter standards, 5-stage SOP schemas, version superseding chains, and offline CLI operations.

On this page

OverviewCore Design Principles3-Tier Architecture OverviewThe 7 Core Memory Types & OKF Pillar TopologyEnabling the Memory SystemGuide Navigation