Proposal: memory-driven modular agent harness architecture

[Grivn]

Status Update (2026-05-21)

This proposal has been accepted as the direction for Mnemon Harness and is now partially implemented in the repository.

The original proposal remains useful as historical design context, but the active source of truth has moved to the formal harness docs and installable loop/projection layout:

• Formal harness docs: docs/harness/
• Modular agent design: docs/harness/modular-agent/DESIGN.md
• Loop standard: docs/harness/LOOP_STANDARD.md
• Host projection contract: docs/harness/HOST_PROJECTION.md
• Harness roadmap: docs/harness/ROADMAP.md
• Lifecycle control plane: docs/harness/LIFECYCLE_CONTROL_PLANE.md
• Canonical loop templates: harness/loops/
• Host projection adapters: harness/hosts/
• Shared ops entrypoints: harness/ops/
• Control contracts: harness/control/

The architecture has also moved from Claude Code-only validation toward a broader host projection model. Current host adapters include Claude Code and Codex, with release-path setup support also existing under mnemon setup for Claude Code, Codex, OpenClaw, and Nanobot-related flows.

Recommended next step: close this proposal as accepted/superseded after follow-up implementation issues are opened for the remaining work.

Proposal

Define a memory-driven modular agent harness architecture for Mnemon-adjacent agent systems.

Mnemon proposes a harness layer for durable agents: the host agent keeps its execution runtime, while external modules turn experience into governed long-term state and use that state to improve future behavior.

The core idea is to separate the host agent runtime from external capability modules. A host agent should keep its own runtime loop, prompt assembly, tool routing, permission model, UI, and native extension mechanisms. External modules should attach through standard extension points rather than replacing the host runtime.

Self-evolution is one important capability built on this architecture, but it is not the whole architecture. The specific self-evolution harness proposal is tracked in #10.

Current Architecture Shape

The host agent owns:

• ReAct or equivalent execution loop
• prompt assembly
• tool routing
• native skill/runtime discovery
• subagent or worker execution
• permission model
• user interface
• session lifecycle

Mnemon owns the harness runtime substrate around that host:

• loop registry and version metadata
• canonical filesystem layout
• environment and path resolution
• host projection into .claude, .codex, or another runtime surface
• state, proposals, reports, audit records, locks, queues, and status files
• shared install, status, uninstall, validation, and future reconcile operations
• optional maintenance scheduling through a future daemon

This keeps Mnemon from becoming a replacement agent framework while also making clear that Mnemon is more than a set of Markdown skills.

Integration Levels

A host agent may support different levels of modularity:

• Markdown-only: the host reads install docs, guides, and protocols directly.
• Hook-capable: the host can receive lifecycle nudges such as Prime, Remind, Nudge, and Compact.
• Skill-capable: the host can discover and invoke protocol skills.
• Subagent-capable: the host can delegate maintenance tasks to workers.
• Projection-capable: Mnemon can render canonical loop assets into host-native surfaces and write a host manifest.
• Full reference host: the host supports hooks, skills, subagents, filesystem config, project/user scopes, and status validation.

Claude Code remains an important reference host, but the architecture boundary is now explicitly host-agnostic. Codex projection and app-server evals provide additional validation pressure.

Design Principles

• Do not replace the host agent runtime.
• Do not require one universal skill format across all hosts.
• Keep loops independently installable.
• Keep memory as the continuity center for skills, goals, evaluation, review, audit, policy, and future replication.
• Keep canonical state inspectable on disk where practical.
• Treat host directories as generated projection surfaces where possible.
• Prefer Markdown-readable contracts before opaque adapters.
• Treat setup scripts as concrete installers, not as the architecture itself.
• Let stronger hosts use richer hooks, skills, subagents, and app-server surfaces without making them mandatory for every host.

Open Work After Acceptance

The remaining work should be tracked as narrower implementation issues rather than continuing this broad proposal:

• Stabilize host capability declarations and compatibility checks.
• Make .mnemon canonical state layout consistent across projections.
• Harden harness/ops install, status, uninstall, upgrade, and recovery behavior.
• Clarify the boundary between experimental harness ops and release-path mnemon setup integrations.
• Define shared proposal, report, audit, lock, queue, and status schemas.
• Expand host projection validation through eval scenarios.
• Keep English and Chinese harness docs synchronized as the contract changes.

Related

• Self-evolution harness proposal: Proposal: self-evolution harness on modular agent architecture #10
• Formal docs: docs/harness/
• English modular agent design: docs/harness/modular-agent/DESIGN.md
• Chinese modular agent design: docs/zh/harness/modular-agent/DESIGN.md
• Harness docs layout PR: docs: reorganize harness documentation #15

[Grivn]

Linked foundation PR: #31

This PR unifies the lifecycle control plane vocabulary and harness layout for the memory-driven modular agent architecture described here. It is scoped as a concept/foundation layer; individual loop projections and host-specific lifecycle semantics should be tightened in follow-up PRs.

[Grivn]

Accepted and superseded by the current harness docs and implementation. The active source of truth is now docs/harness/, harness/loops/, harness/hosts/, harness/ops/, and harness/control/. Future work will be tracked as concrete implementation tasks when needed.