Skip to main content

Context & Memory Management - APM v0.5

This document details how APM implements progressive context and memory management for cost-effective, scalable project execution.

Memory System Architecture​

APM uses a Dynamic Markdown (MD) File System, organized as a layered directory structure that mirrors the phases and tasks in the Implementation Plan. This progressive "Dynamic Memory Bank" is maintained by the Manager Agent, who creates the overall structure, while individual documents —called Memory Logs— are populated by Implementation Agents as they record execution details of specific tasks.

Example of a typical Dynamic Meory Bank:

.apm/Memory/
├── Memory_Root.md                  # High-level Project State (Manager Scope)
├── Phase_01_Foundation/            # Phase Directory
│   ├── Task_1_1_Project_Setup.md   # Atomic Task Log (Implementation Scope)
│   ├── Task_1_2_Database.md
│   └── ...
└── Phase_02_Core_Features/
    └── ...

Stateless Operations (Ad-Hoc Agents)​

Unlike Manager and Implementation Agents, Ad-Hoc Agents are stateless. They do not create Memory Logs or have dedicated folders within the .apm/Memory/ system. Their outputs are ephemeral—meant to be pasted back into the main Agent’s session as immediate solutions, without being stored in the project's persistent history. When an Ad-Hoc Agent is used for a task, the corresponding Memory Log for that task will note the delegation and summarize relevant details for the Manager’s awareness.

Memory Artifact Hierarchy​

  • The Memory Root (Memory_Root.md): It is intended for the Manager Agent, providing concise, high-level summaries of completed phases with references to the individual Memory Logs, global architectural decisions, and current project status, enabling a clear view of the project's overall trajectory without requiring review of individual task logs.

  • Phase Directories & Memory Logs: Phase Directories contain task Memory Logs that are written by Implementation Agents and read by the Manager Agent. Each Memory Log provides a compact summary of the corresponding task's execution, and is named according to the convention Task_<Phase>_<ID>_<Slug>.md (e.g., Task_1_2_Database_Schema.md), as mapped from the Implementation Plan.

Context Archive: Scaling & Onboarding​

As the project progresses, the Memory System evolves into a comprehensive context archive. This archive maps the project's specifications (the Implementation Plan) directly to its execution history (the Memory Logs).

This structured mapping enables efficient scalability:

  • Seamless Onboarding: New Agents can get up to speed by reviewing only the Memory Logs relevant to their assinged tasks —such as previous decisions, outputs, and files— without needing to read the entire codebase or unrelated history.
  • Efficient Expansion: When introducing new features, Agents can target specific historical logs (e.g., "Read Task_1_2_Database.md"). This allows for precise information retrieval without loading the entire project history.

The specific protocol for injecting dependencies into an Agent is detailed in Context & Prompt Engineering > Cross-Agent Context Injection.

The Memory Log Artifact​

The Memory Log is the atomic unit of project history. It acts as a concrete record, distilling the detailed execution information from an Implementation Agent into a standardized file format.

Standardized Log Format​

To ensure parsing accuracy by the Manager, every Memory Log follows a strict Markdown structure:

  1. Status Metadata: YAML frontmatter indicating status: complete or important_findings:yes etc.
  2. Execution Summary: A concise narrative of what was built.
  3. File Manifest: A list of all files created or modified (e.g., src/components/Button.tsx).
  4. Key Decisions: Technical trade-offs made during execution.
  5. Next Steps: Guidance or recommendations for the Manager.

The Manager reads this log to verify the task without needing to parse the raw code files, effectively reducing the context load by orders of magnitude.

Handover Protocol​

When an Agent's context window fills, APM employs a Two-Artifact Handover System to transfer "working memory" to a new instance.

Handovers in APM are efficient because the new Agent does not inherit the complete execution details of the previous session. It inherits only the Memory Logs, task outputs and the Handover Artifacts. This ensures that the "noise" of debugging, trial-and-error, and intermediate reasoning is filtered out, allowing a project to sustain multiple consecutive handovers without context degradation.

The Handover File​

A Markdown file generated by the outgoing Agent following this naming convention: <Agent>_Handover_File_<SessionID>.md

  • Purpose: Captures the uncommitted or tacit knowledge that doesn't belong in a formal Memory Log.
  • Content:
    • User Preferences: "User prefers concise code comments."
    • Workflow Insights: "The linter is strict about unused vars; run fix before committing."
    • Undocumented State: "I created a temp file debug.log that needs deletion."

The Handover Prompt​

A Markdown code block generated by the outgoing Agent.

  • Purpose: Acts as the "bootloader" for the new Agent.
  • Content:
    • Instructions to read the specific Handover_File.
    • Instructions to read the previous Agent's Memory_Logs to regain recent history.
    • A directive to pause for User Verification before acting.

Context Saturation & Limits​

Even with this robust system, context limits impose a physical ceiling. A single Agent role (e.g., Agent_Frontend) can typically sustain 3-4 handovers before the volume of accumulated context becomes too large to load effectively.

If a specific Agent role reaches this saturation point, it indicates the need for a Workload Split: The Manager should update the Implementation Plan and split the saturated role (e.g., Agent_Frontend) into two focused roles (e.g., Agent_Frontend_Components and Agent_Frontend_State). This is usually a User-ordered decision.