Memory
Delivery
How Mopheus delivers memories to agents at runtime, builds dynamic MEMORY.md index tables, negotiates ETag caching, and enforces read-only sandbox isolation.
When an AI agent starts a task, how does it access relevant past knowledge without getting overwhelmed by thousands of unrelated cards? How is MEMORY.md generated, and how does Mopheus guarantee that environment facts never leak across assets?
Mopheus employs a tiered filtering mechanism (L0/L1/L2) on the server, generates a lightweight task-scoped MEMORY.md navigation index, and delivers cards to the execution node via ETag-negotiated caching and Bubblewrap read-only sandbox projection.
The 3-Tier Delivery Filtering Model (Server-Side)
When an agent claims a task or when an automated background job is scheduled, the server dynamically synthesizes the memory context through three disciplined tiers:
[Task Context Signals]
(Ticket title/description, requester user_id, asset_id, labels)
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3-Tier Filtering Model (RecallMemories) │
├─────────────────────────────────────────────────────────────┤
│ │
│ [L0 Tier: Universal Baseline Facts] (Zero Scope Binding) │
│ • WHERE asset_id IS NULL AND user_id IS NULL │
│ • Global environment facts, preferences, reference docs │
│ │ │
│ ▼ │
│ [L1 Tier: Requester Personal Preferences] │
│ • WHERE memory_type = 5 AND user_id = origin_user_id │
│ • Communication style, language, and review habits │
│ │ │
│ ▼ │
│ [L2 Tier: Targeted Entity & Contextual Candidates] │
│ • Matches exact asset_id, error codes, and stack labels │
│ • Asset-specific configurations, relevant error runbooks │
│ │
└───────────────────────────┬─────────────────────────────────┘
│
▼
[Dynamic MEMORY.md Index Construction]
│
▼
[ETag Manifest Calculation & Delivery]1. Core Boundaries: Asset Isolation & Tiered Rules
Environment facts in Mopheus are strictly bound to assets (asset_id) rather than injected globally:
L0 Tier: Universal Baseline Facts (Zero Scope Binding)
- SQL Condition:
WHERE workspace_id = $1 AND memory_type IN (3, 5, 6) AND enabled = TRUE AND superseded_by IS NULL AND (context_tags->>'asset_id' IS NULL OR context_tags->>'asset_id' = '') AND (context_tags->>'user_id' IS NULL OR context_tags->>'user_id' = '') - Injected Content: Truly global shared conditions (such as container read-only path rules, proxy settings, generic architectural guidelines).
- Strict Exclusion: Any card tagged with an
asset_idis unconditionally excluded from L0!
L1 Tier: Requester Personal Preferences (Origin User Preference)
- Injected only when the task has an explicit
origin_user_id. - Recalls preferences saved by that specific user (
memory_type = 5 AND context_tags->>'user_id' = $userID). - Tasks triggered by other team members are completely unaffected by another user's personal preferences.
L2 Tier: Targeted Entity & Contextual Candidates (Asset & Context Recall)
- Asset-Specific Facts: When a task specifies a target asset (
asset_id), the system uses JSON containment matching (context_tags @> {"asset_id": "..."}) to recall facts bound to that exact asset (e.g., host CPU/memory, instance topology). - Dynamic Context Matching: Standardized error codes (such as
ORA-01555,42P01) and stack labels extracted from the ticket trigger corresponding troubleshooting runbooks.
Dynamic MEMORY.md Task Index Construction
Instead of dumping full card texts into the agent's prompt, the server dynamically synthesizes a concise Markdown navigation index at .claude/memory/MEMORY.md.
Index File Structure
# Task Memory Navigation Index
This is the workspace memory repository index for the current task. Skim primary anchors and matched recommendations first, then navigate to detailed cards via relative paths.
## Primary Anchors
- [API error codes must be defined via errx](conventions/preferences/1528fa6d-2786-4c33-9e4e-a2e4e84ca7d7.md) (preference)
- [Monorepo and Landing Page Split Resolution](conventions/corrections/2fa85f64-0000-0000-0000-000000000002.md) (human_correction)
## Knowledge Map (OKF Topology)
- `runbooks/`: Operational SOPs and disaster recovery (`errors/`), pitfalls & incident postmortems (`pitfalls/`), verified execution playbooks (`playbooks/`).
- `facts/`: IT asset topology and configuration baselines (`specs/`).
- `conventions/`: Human corrections (`corrections/`) and user/operational preferences (`preferences/`).
- `docs/`: Ingested system architecture manuals and long-form official reference documentation.
## Top Matched Recommendations
> **Notice**: Showing top 10 prioritized recommendations of 12 locally mounted knowledge cards. Additional 2 cards are cataloged below.
| Type | Title | Description | Labels | Relative Path | Occurrence | Last Seen |
| :--- | :---- | :---------- | :----- | :------------ | :--------- | :-------- |
| fact | /src and /home/moclaw-dev/repos are mounted read-only | Sandbox mount layout | sandbox, linux | [facts/specs/7ca47dae-9dab-4390-8fee-a8284d31f079.md](facts/specs/7ca47dae-9dab-4390-8fee-a8284d31f079.md) | 1 | 2026-10-10 |
| preference | API error codes must be defined via errx | Backend error code standard | go, backend | [conventions/preferences/1528fa6d-2786-4c33-9e4e-a2e4e84ca7d7.md](conventions/preferences/1528fa6d-2786-4c33-9e4e-a2e4e84ca7d7.md) | 1 | 2026-10-10 |
| risk | save-images.sh is incompatible with Docker 29 containerd store | — | docker, release | [runbooks/pitfalls/c971377d-839b-43e8-bf11-4ff24de977ce.md](runbooks/pitfalls/c971377d-839b-43e8-bf11-4ff24de977ce.md) | 1 | 2026-10-10 |
| resolution | PostgreSQL JSONB CAST type conversion fix | Explicit cast for jsonb path queries | postgres, sql | [runbooks/errors/b8fc3025-ceb6-4be9-a8a6-03898ae25e92.md](runbooks/errors/b8fc3025-ceb6-4be9-a8a6-03898ae25e92.md) | 3 | 2026-10-10 |
## Additional Mounted Cards (2)
The following background cards are also mounted in local OKF directories and can be inspected via your preferred file viewing tool or `grep`:
- [Nginx Gateway Timeout Investigation](runbooks/errors/d1234567-0000-0000-0000-000000000001.md) (`error_resolution`)
- [General Development Standards Manual](docs/e1234567-0000-0000-0000-000000000002.md) (`reference_doc`)
## Usage Guidelines
- **Verify Deeply**: Table summaries are triage hints, not conclusive evidence. Always inspect the full card via your preferred file viewing tool before relying on it.
- **Explore Local Cards**: In addition to the top recommendations, all mounted cards listed above are immediately available in the local directory tree.
- **Dynamic Retrieval**: If this index does not cover what you need, run `mop memory retrieve "<query>"` with descriptive natural language, or `mop memory get <id> --save` to fetch full docs into `.memory/`.
- **Durable Persistence**: This directory is an ephemeral read-only projection for this task run. Never write memory files directly to disk; use `mop memory store` to persist reusable facts into the workspace.Key Design Principles:
- Deterministic Relative Links: Links strictly follow the OKF 4-pillar directory schema (
facts/specs/,conventions/,runbooks/,docs/), allowing agents to read them directly via standard file-reading tools. - Triage Hints, Not Conclusive Evidence: The system prompt instructs agents that index summaries are only triage clues; agents must read the complete card before taking decisive actions.
Host Node Caching & ETag Negotiation (Daemon)
To avoid network congestion and database I/O spikes caused by repeated full downloads, the Mopheus Daemon maintains a workspace-level shared Cache Pool:
[Server Issues Memory Payload & ETag]
│
▼
┌────────────────────────────────┐
│ Daemon Checks Local Cache ETag │
└───────────────┬────────────────┘
│
┌────────────────┴────────────────┐
▼ ▼
[ETag Match] [ETag Stale]
│ │
(304 Not Modified) (Download Changed Cards)
│ │
▼ ▼
[Reuse Local Cache] [Acquire .lock, Atomic Write & Swap]
│ │
└────────────────┬────────────────┘
│
▼
[Project to Sandbox .claude/memory/]- Weak ETag Negotiation: The server computes a weak ETag based on active card IDs and update timestamps. If the daemon presents a matching ETag, the server returns
304 Not Modified, transferring zero card bytes. - Workspace Cache Pool: Daemons maintain shared card files on the host. Concurrent tasks within the same workspace share the same underlying card cache.
- Concurrency Safety: Multi-process cache synchronization is protected by file locks (
.lock) and atomic file swaps, preventing race conditions or torn reads.
Sandbox Security & Read-Only Isolation
To prevent agent tasks from corrupting or tampering with the central knowledge base:
1. Physical Read-Only Mount
- Linux Production: Daemons use Linux namespaces and Bubblewrap (
--ro-bind) to project the host Cache Pool into the sandbox container at.claude/memory/as a read-only filesystem. - Cross-Platform / Development: Non-Linux environments use filesystem symbolic links.
2. Strict Isolation Guard
- No Shared Index Pollution: The
MEMORY.mdindex file is generated exclusively within the task's private directory, never in the shared host Cache Pool. Each task sees its own custom index. - Write Prevention: If an agent attempts to overwrite a card in
.claude/memory/, the OS returnsRead-only file system. Any modifications made in non-isolated environments are wiped upon sandbox cleanup and never synced back to the database.
Agent Interaction Contract
Mopheus primes agents via the system prompt (writeSlimCommandsMemory) with a disciplined cognitive contract:
- Step 1: Check Index First
Before running exploratory commands or attempting to fix unknown errors, read.claude/memory/MEMORY.mdto see if a verified solution already exists. - Step 2: Read Full Cards on Demand
Open and inspect matching cards via their relative paths to review preconditions and verified steps. - Step 3: Dynamic Retrieval Fallback
If an unexpected error occurs during execution that is not inMEMORY.md, query the server database dynamically usingmop memory retrieve "<query>". - Step 4: Controlled Persistence
New insights gained during the task must be stored back to the database viamop memory store --type ....
Specification
In-depth exploration of PostgreSQL persistence, OKF YAML Frontmatter standards, 5-stage SOP schemas, version superseding chains, and offline CLI operations.
Retrieval
Deep dive into Mopheus's multidimensional scoping architecture (asset, stack, project, tags), native multi-language full-text search, and precedence ranking.