Specification

A reliable enterprise memory system must guarantee that knowledge is structured, versioned, portable, and resistant to corruption. Mopheus achieves this by combining PostgreSQL as the centralized single source of truth with the Open Knowledge Format (OKF) for file representation and exchange.

This document details the OKF card specification, storage architecture, version deprecation chains, and offline CLI workflows.

Centralized Storage: Single Source of TruthCopy Anchor Link

In Mopheus, the relational database is the sole persistent Single Source of Truth (SSOT) for all memory cards. Agent execution sandboxes are ephemeral; any memory created or refined in a sandbox must be committed back to the database via API or CLI.

              ┌─────────────────────────────────────┐
              │    Centralized PostgreSQL Database  │
              │                                     │
              │  • memory (Primary, content_tsv)    │
              │  • memory_source (Ticket provenance)│
              │  • memory_distillation (Audit log)  │
              └──────────────────┬──────────────────┘
                                 │
                 ┌───────────────┴───────────────┐
                 │                               │
        Read / Recall                   Write / Update
                 │                               │
                 ▼                               ▼
      ┌──────────────────────┐        ┌──────────────────────┐
      │   Daemon / Sandbox   │        │     Mopheus CLI      │
      │ (.claude/memory/)    │        │  (mop memory ...)    │
      │ *Read-Only Mirror*   │        │ *Controlled Gateway* │
      └──────────────────────┘        └──────────────────────┘

Primary Database Schema & IndexingCopy Anchor Link

• memory Table:
  • id (UUID): Primary key of the memory card.
  • workspace_id (UUID): Tenant boundary identifier, enforcing strict workspace data isolation.
  • memory_type (INT): Enum representing the 7 OKF memory types (0 to 6).
  • title (VARCHAR 100): High-signal summary describing the problem, fact, or procedure.
  • content (TEXT): Core content body (plain Markdown or structured JSON).
  • context_tags (JSONB): Dynamic context metadata (asset_id, db_type, project_id, profile_id), indexed with GIN containment (@>).
  • occurrence_count (INT): Cumulative count of times this memory was validated across tickets.
  • recall_hit_count (BIGINT): Total number of times this card was recalled and delivered into agent tasks.
  • content_tsv (TSVECTOR): Pre-computed search vector with Title weighted 'A' and Content weighted 'B', indexed via GIN for sub-millisecond multi-language full-text search.
  • superseded_by (UUID): Points to the successor memory card that replaced this one.
  • enabled (BOOL): Logical availability flag.
• memory_source Table:
  • memory_id (UUID): Foreign key referencing memory.id.
  • ticket_id (UUID): Originating or confirming ticket ID, maintaining complete audit provenance.
• memory_distillation Table:
  • Records ticket-level distillation lifecycle and audit data (ticket_id, workspace_id, db_type, distilled_at, distilled_by, skipped_reason). The legacy memory_count column is deprecated and is not maintained or exposed; use the ticket memory list for current associations.
• Anti-Pattern Guard:
  • Sandbox Local Files are Ephemeral: Changes written directly into .claude/memory/ on disk will never synchronize back to PostgreSQL and are permanently lost upon sandbox teardown.
  • Controlled Ingestion: All memory creation, updates, and deprecation must be executed through mop memory store or mop memory update.

OKF (Open Knowledge Format) SpecificationCopy Anchor Link

OKF is a unified knowledge card standard designed for AI agents and human engineers, combining YAML Frontmatter with a structured Markdown body.

1. YAML Frontmatter SpecificationCopy Anchor Link

Every memory card begins with an authoritative YAML Frontmatter block:

---
id: c971377d-839b-43e8-bf11-4ff24de977ce
type: failure_scenario
title: "save-images.sh is incompatible with Docker 29 containerd image store"
occurrence: 1
last_seen_at: 2026-10-10T14:19:07Z
superseded_by: null
component: install-script
description: "save-images.sh fails when containerd image store is enabled on Docker 29"
labels:
  - docker
  - release
repo: mopheus
scope: known-defect
---

Field Definitions:Copy Anchor Link

2. Content Formats: Markdown Body vs. 5-Stage JSON SOPCopy Anchor Link

Depending on the memory type, the content body follows one of two distinct formats:

Freeform Structured Markdown (resolution, risk, fact, correction, preference, reference)Copy Anchor Link

Written in GitHub Flavored Markdown, outlining symptoms, root cause, and remediation:

Confirmed during v2.2.10 release testing: install/scripts/save-images.sh fails on Docker 29.6.0 with the containerd image store.

## Failure Chain
1. Docker 29 moved --platform from `docker inspect` to `docker image inspect`, leaving image_id empty.
2. When falling back to save_ref, `docker save` attempts to serialize the entire manifest list; missing architecture layers trigger NotFound.

## Remediation
Use `docker image inspect --platform` to extract platform metadata, and pass `docker image save --platform $DOCKER_PLATFORM $image`.

Structured JSON Body (procedure / success_playbook)Copy Anchor Link

For standard operating procedures (procedure), the content must be a self-contained 5-stage JSON object:

{
  "fault": "PostgreSQL 17 jsonb path queries fail with type mismatch when missing explicit casts",
  "preconditions": [
    "Target database is PostgreSQL 17+",
    "Table schema contains jsonb columns"
  ],
  "steps": [
    "Identify SQL queries using jsonb arrow operators without casts",
    "Replace col->>'field' with (col->>'field')::target_type",
    "Run EXPLAIN ANALYZE to verify index scans are preserved"
  ],
  "validation": [
    "Execute regression tests and verify HTTP 200 responses",
    "Inspect pg_stat_activity to ensure no hanging locks"
  ],
  "rollback": "Restore prior view definition or run ALTER TABLE downgrade script if queries produce inconsistent business outputs"
}

Rollback Convention: Reversible operations must include explicit rollback instructions. Irreversible destructive operations (e.g. DROP, TRUNCATE) must state "This operation is not reversible.".

3. OKF 4-Pillar Semantic Directory LayoutCopy Anchor Link

When mounted or exported, memory cards are organized into a strict 4-pillar directory structure:

1. runbooks/ (Operational Playbooks & Troubleshooting):
   • runbooks/errors/<id>.md: Stores error_resolution (root-cause diagnosis and fixes).
   • runbooks/pitfalls/<id>.md: Stores failure_scenario (known risks and incompatibilities).
   • runbooks/playbooks/<id>.md: Stores success_playbook (5-stage JSON SOPs).
2. facts/ (Static IT Infrastructure Specifications):
   • facts/specs/<id>.md: Stores environment_fact (host specifications, network topologies, mount points).
3. conventions/ (Architectural Standards & Corrections):
   • conventions/corrections/<id>.md: Stores human_correction (human expert feedback and overrides).
   • conventions/preferences/<id>.md: Stores preference (team coding rules and user habits).
4. docs/ (Reference Manuals & Architectural Guides):
   • docs/<id>.md: Stores reference_doc (long-form architecture manuals and interface specifications).

Memory Lifecycle & Version DeprecationCopy Anchor Link

Memories are living artifacts that evolve alongside infrastructure.

1. Deduplication & Occurrence CounterCopy Anchor Link

When new memories are ingested via CLI or distillation, the system performs text similarity matching using pg_trgm:

• Matching Type & High Similarity (thresholds: 0.28 for procedure, 0.25 for preference, 0.30 for default):
  • The system avoids creating duplicate rows and reuses the existing memory ID.
  • If corroborated by a new ticket, occurrence_count increments by 1, and last_seen_at is updated.
  • Cards with higher validation counts enjoy elevated confidence weighting in subsequent task matching.

2. Explicit Version Superseding Chains (--supersedes)Copy Anchor Link

When an older procedure or workaround is replaced by a permanent fix, the new card explicitly supersedes the predecessor:

mop memory store \
  --type risk \
  --title "save-images.sh Docker 29 compatibility fix" \
  --content "..." \
  --supersedes c971377d-839b-43e8-bf11-4ff24de977ce

• Backend Logic: Sets the predecessor's superseded_by pointer to the new card's UUID, and marks the predecessor as enabled = false.
• Safe Rollback: If the successor card is later deleted, the predecessor automatically reactivates (enabled = true), preventing gaps in institutional memory.

Offline CLI Management & InteroperabilityCopy Anchor Link

Mopheus provides CLI utilities to export, import, and validate memory cards:

1. Full Export to Local OKF HierarchyCopy Anchor Link

Export all memories in the workspace into the standardized 4-pillar directory structure with a root MEMORY.md index:

mop memory export --dir ./workspace-memories

The exported tree can be directly checked into Git for version tracking.

2. Static Directory ValidationCopy Anchor Link

Validate cards before importing to ensure compliance with OKF standards:

mop memory validate --dir ./workspace-memories

Validation Checks:

• Files must reside in one of the 4 pillar directories (runbooks/, facts/, conventions/, docs/).
• Valid YAML Frontmatter enclosed by ---.
• type matches one of the 7 supported memory types or aliases.
• Non-empty content body.

3. Bulk Directory ImportCopy Anchor Link

Import a validated OKF directory tree into the current workspace:

mop memory import --dir ./workspace-memories

• Idempotent: updates existing cards (if timestamps are newer) or inserts new records.
• Ideal for initializing knowledge bases in CI/CD pipelines.

File Scanning & Filtering Boundaries for ImportCopy Anchor Link

• Non-Markdown Files Automatically Ignored: The importer traverses the directory and processes only files with the .md extension. Any media assets, images (PNG/JPG), Office files (Word/Excel), PDFs, videos, or archives stored in the directory are quietly skipped; the root MEMORY.md index file is also excluded.
• Strict Validation for Markdown Files: Every .md file discovered in the directory is treated as a candidate memory card and must strictly adhere to the OKF YAML Frontmatter specification (valid --- delimiters, required type field, and non-empty content). Plain Markdown files lacking Frontmatter (such as stray README.md files) will cause parsing to fail with PARSE_FAILED.
• Pre-Import Validation: Always run mop memory validate --dir <dir> prior to importing to catch schema and formatting errors early.