OpenAB + Codex + k3s Memory Use Case

• Use case ID: memory.openab-codex-k3s
• Protocol: memory@0.1.0
• Evidence: field-tested
• Conformance: mapped — historical lifecycle evidence maps through memory:L4 against memory@0.1.0; the memory@0.2.0 withdrawal/erasure contract and current item schema were not revalidated
• Validation scope: deployment-derived architecture, scheduling checks, and operational pitfalls; live cluster was not rechecked during the 2026-08-13 withdrawal-protocol alignment review
• Reproducibility: partial — the binding is environment-specific and requires an equivalent cluster/runtime
• Level namespace: memory
• Last reviewed: 2026-08-13

1. Context

This use case describes an agent memory system for a long-running OpenAB + Codex environment on k3s.

The system must let an agent:

• Keep memory across sessions.
• Preserve memory across Pod restarts, Deployment rollouts, and version upgrades.
• Separate short-term notes, long-term knowledge, and operational pitfalls.
• Distill memory automatically without letting it grow into a mess.
• Preserve a manual audit path without requiring daily human curation.

The design is a practical implementation of Agent-first Memory Architecture.

Protocol alignment note

This deployment predates memory@0.1.0. Its persistence, scheduling, archive-first workflow, distillation, and operational failures are real evidence, but the documented binding still permits direct topic writes and legacy [待清理] markers. Before claiming current memory@0.2.0 conformance, route captures through the inbox, add stable id, kind, Source, and subject for state, adopt the closed Status vocabulary, validate exact-subject non-destructive supersede, and implement withdrawal routing, control records, anti-resurrection, and authorized-erasure receipts. The evidence label does not certify the current schema.

2. Design philosophy

This design combines several ideas:

1. OpenAB steering-design-guide — Hot / Warm / Cold memory layering.
2. Local Kiro memory pipeline — memory.md + archive + autodream + topics.
3. Codex instruction and skill model — AGENTS.md as the hot entry and .codex/skills/* as triggered workflow bodies.

Final principles:

• AGENTS.md stores the hot behavior contract, rules, and memory entry points, not short-term memory bodies.
• memory.md is a hot inbox, not the final knowledge base.
• index.md is cold/warm navigation, not a second garbage pile.
• topics/ stores distilled long-term knowledge.
• archive/ stores raw snapshots and traceable evidence.
• Archive and autodream must be separated: preserve first, distill second.

3. Directory structure

/home/node/
├── AGENTS.md
├── memory/
│   ├── README.md
│   ├── index.md
│   ├── memory.md
│   ├── log.md
│   ├── archive/
│   │   └── YYYY-MM-DD.md
│   ├── topics/
│   │   ├── user-preferences.md
│   │   ├── environment.md
│   │   ├── workflows.md
│   │   ├── decisions.md
│   │   ├── memory-system-design.md
│   │   └── operational-pitfalls.md
│   ├── scripts/
│   │   └── archive-memory.sh
│   └── k8s/
│       └── archive-cronjob.yaml
├── .openab/
│   └── cronjob.toml
└── .codex/
    └── skills/
        └── memory-manager/
            └── SKILL.md

4. Layering model

5. File responsibilities

AGENTS.md

AGENTS.md only does four things:

1. Defines personality and rules.
2. Tells the agent where the memory system is.
3. Defines when to read memory.
4. Defines when to write memory.

It does not store short-term memory bodies. This avoids bloat and attention dilution.

memory/memory.md

This is the hot inbox.

Use it when:

• The user explicitly says “remember”, “don't forget”, “from now on”, or “this is my preference”.
• A high-value note is discovered but not yet judged worthy of long-term distillation.

Rules:

• Do not store full conversation transcripts.
• Store reusable conclusions only.
• Treat it as an inbox, not a knowledge base.

memory/log.md

This is operational trace, not knowledge content.

It records:

• bootstrap
• archive
• archive-skip
• autodream
• autodream-skip
• review

It is both an audit entry point and a troubleshooting clue.

memory/index.md

This is the wiki homepage.

It should:

• Tell the agent which topic to read first.
• Maintain a recent activity section.
• Track topic status.
• Stay small enough to scan quickly.

It should not:

• Paste archive content back into the index.
• Carry long bodies of text.

memory/topics/*.md

These are the real long-term knowledge pages.

Current topic categories:

• user-preferences.md — long-term user preferences, language, style, and tool boundaries.
• environment.md — k3s, OpenAB, Codex, PVC, scheduling, and deployment facts.
• workflows.md — memory write, archive, autodream, and review SOPs.
• decisions.md — confirmed architecture and strategy decisions.
• memory-system-design.md — design of the memory system itself.
• operational-pitfalls.md — implementation pitfalls and fixes.

memory/archive/*.md

Archive files preserve daily raw memory snapshots.

They are:

• evidence
• source tracing
• distillation input

They should not be loaded first in normal work.

6. Memory write rules

The following records the historical binding. Step 3 is a declared deviation from current memory@0.2.0, whose capture path writes the inbox first and lets the governed distillation path update topics.

When the user explicitly says:

• remember
• don't forget
• from now on
• this is my preference
• 记住
• 不要忘了
• 以后都这样
• 这是我的偏好

The agent should:

1. Compress the content into a reusable conclusion.
2. Write it to memory/memory.md.
3. If it is clearly long-term and stable, optionally update the relevant topics/*.md.
4. Append an operation record to memory/log.md.

Principles:

• Do not copy entire conversations.
• Do not treat temporary emotion as long-term knowledge.
• Do not directly overwrite old knowledge.
• Add first, clean later.

7. Automation

This implementation is hybrid.

Stage 1: archive

Execution: Kubernetes CronJob

Time: Asia/Shanghai 04:10

Purpose:

• Pure shell, no AI.
• Move substantive content from memory.md to archive/YYYY-MM-DD.md.
• Recreate a blank hot inbox.
• Update log.md.

Why Kubernetes CronJob:

• Archive is mechanical.
• It should not depend on agent judgment.
• Even if AI fails, raw memory is preserved first.

Stage 2: autodream

Execution: OpenAB usercron

Time: Asia/Shanghai 04:20

Purpose:

• Read today's archive.
• Read index.md.
• Read relevant topics/*.md on demand.
• Extract long-term reusable knowledge.
• Update index.md.
• Create or update topics/*.md when needed.
• Leave a distillation record in log.md.

Why OpenAB usercron:

• Autodream is essentially “send a prompt to the agent to distill memory”.
• Scheduling this through OpenAB is natural because the work belongs to the agent runtime.

8. Flow

Daytime usage                         04:10                    04:20
─────────────────────────────────────────────────────────────────────
session / chat writes memory.md  →   archive preserves it   →   autodream distills it
                                    (CronJob / shell)          (OpenAB usercron / agent)

Outputs:

• archive/YYYY-MM-DD.md
• recreated memory.md
• updated index.md
• updated topics/*.md
• log.md operation trace

9. Distillation rules

Autodream is conservative, but these are legacy deployed rules. Free-form [待清理] must be migrated to the current closed Status vocabulary before claiming protocol conformance.

Rules:

• Incremental updates only.
• Do not directly delete existing knowledge.
• Mark stale items as [待清理].
• Do not paste archive content back into index.md.
• Preserve source dates.
• Use index.md only for navigation and recent activity.
• Create or update topic pages only when useful.

This prevents two disasters:

1. AI accidentally deleting useful old knowledge.
2. Cold storage growing back into a hot garbage pile.

10. Operational pitfalls

10.1 ConfigMap-mounted AGENTS.md is read-only

If AGENTS.md is mounted from a ConfigMap, the Pod can read it but cannot update the true file.

Conclusion:

If AGENTS.md must be mutable, it should live on PVC as the source of truth.

10.2 kubectl binary does not imply cluster access

Having kubectl in PATH does not mean it can reach the cluster.

Without ~/.kube/config or KUBECONFIG, it may try:

localhost:8080

and fail.

10.3 KUBECONFIG should not rely on shell profiles

.profile and .bashrc are not reliable for long-running containers or agent child processes.

More stable options:

• Deployment env
• Helm values
• CronJob env
• OpenAB config

10.4 Scheduling must be validated in layers

Do not only check that YAML exists.

Verify:

1. CronJobs appear in the cluster.
2. Deployment logs show usercron loaded.
3. The time window passes.
4. Archive/autodream leaves actual traces in files and logs.

10.5 memory.md must not become final knowledge

memory.md is an inbox, not a wiki.

If it becomes the final knowledge base, the system loses the hot/warm/cold separation.

11. Evidence boundary

What this use case supports

• A real containerized binding separated writable persistent memory from immutable deployment configuration.
• Archive-first scheduling and layered runtime checks exposed concrete k3s, environment, and cron pitfalls.
• The lifecycle survived beyond one chat session and one process lifetime.

What it does not support

• End-to-end conformance with the current memory@0.2.0 item, withdrawal, and erasure contract.
• Current cluster health; the live environment was not rechecked during this review.
• A claim that ConfigMap, PVC, CronJob, or OpenAB is required by the general protocol.

12. Essence

One-sentence version:

Daytime notes enter the hot inbox, nighttime archive preserves them losslessly, the agent conservatively distills them, and the result becomes persistent, searchable, auditable cold knowledge.

Metaphor:

AGENTS.md is the hot behavior contract.
memory.md is the temporary box.
index.md is the signpost.
topics/ is the shelf of artifacts.
archive/ is raw evidence.
log.md is the footprints.
archive + autodream is the daily mechanism that maintains the knowledge base.