Memory and Context

Purpose

This page documents the lab's memory model. The Coordinator owns the memory layer; this page is the canonical reference for the structure, the policies, and the boundaries.

The memory model has three layers:

1. Long-term memory (MEMORY.md) — curated, durable facts.
2. Daily logs (memory/YYYY-MM-DD.md) — raw chronological record.
3. Session context — the in-memory state of the current session.

Plus two derived layers that are part of the same ecosystem:

4. Skill artifacts (SKILL.md, TOOL.md) — capabilities the agent activates.
5. Project notes — per-project context that the agent can recall on demand.

The layers are complementary, not redundant. Each has a purpose; mixing them creates confusion.

Long-term memory (MEMORY.md)

MEMORY.md is the lab's curated long-term memory. It is the distillation of everything the lab has learned that is worth keeping.

Properties

• Single file. One MEMORY.md per agent (the main agent has one; the specialized agents have their own or none).
• Loaded only in the main session. The file is sensitive (it can contain personal context) and is never loaded in shared or group contexts.
• Editable freely in main sessions. The Coordinator can read, edit, and update MEMORY.md when the user asks.
• Curated, not raw. Only the distilled essence goes here, not the raw daily log.

What goes in

• Significant decisions and their rationale.
• Important facts about the lab (machine specs, ports, paths, conventions).
• Lessons learned from past mistakes.
• Identity and relationship information (the user-agent bond).
• Long-term preferences and policies.

What does NOT go in

• Raw daily logs (those go in memory/YYYY-MM-DD.md).
• Secrets, credentials, or API keys.
• In-progress or speculative plans.
• Session-specific state (use the session context for that).

Maintenance

MEMORY.md is maintained by the Coordinator. The Coordinator:

• Reads MEMORY.md at the start of each session.
• Writes to MEMORY.md when a significant fact is learned.
• Periodically distills daily logs into MEMORY.md and removes outdated entries.
• Updates MEMORY.md to reflect the current state of the system (e.g., model changes, port changes).

The Coordinator never edits MEMORY.md in shared contexts. The file is for the main session only.

Daily logs (memory/YYYY-MM-DD.md)

Daily logs are the raw chronological record of what happened in the lab on a given day. One file per day.

Properties

• One file per day. Filename is memory/YYYY-MM-DD.md (UTC date).
• Append-only. Daily logs are historical records; the Coordinator does not edit them after the day ends.
• Loaded on demand. The Coordinator reads the current day's log at the start of each session and older logs when needed.
• Not curated. Daily logs are raw notes; the distillation into MEMORY.md happens periodically.

What goes in

• Decisions made and their context.
• Errors encountered and how they were resolved.
• Tasks completed (and how).
• Lessons learned (these may later be moved to MEMORY.md).
• Anything the user explicitly asked to be remembered.

What does NOT go in

• Secrets or credentials.
• Outputs of long-running processes (use artifact files for that).
• Code snippets longer than a few lines (use a reference to the file).

Retention

Daily logs are kept indefinitely by default. The Coordinator can be configured to archive logs older than a year to a separate directory.

Session context

Session context is the in-memory state of the current session. It is created when the session starts and discarded when the session ends.

Properties

• In-memory. Not persisted to disk (unless the user explicitly asks).
• Per-session. Each session has its own context.
• Loaded with the session. The Coordinator reads the context at the start of each session.

What goes in

• The current task and its state.
• Variables and parameters for in-flight work.
• Conversation history within the session.
• Cached tool results (for the duration of the session).

What does NOT go in

• Anything that should survive the session (use daily logs or MEMORY.md).
• Sensitive data that the user does not want in memory.

Skill artifacts

Skill artifacts are the files that describe a capability the agent can activate. They are part of the memory ecosystem but are loaded on demand, not at session start.

SKILL.md

A SKILL.md file describes a skill. It has:

• A name and a description.
• A list of trigger phrases (when to use the skill).
• A workflow (how to use the skill).
• A list of inputs and outputs.

The Coordinator activates a skill when the user's request matches the skill's trigger phrases. The activation loads the skill's instructions into the session context.

TOOL.md

A TOOL.md file describes a tool. It is similar to SKILL.md but for tools (commands the agent can invoke). The Coordinator loads the TOOL.md when it needs to use the tool.

The structure of a TOOL.md is documented in Tool Spec.

Project notes

Project notes are per-project context that the agent can recall on demand. They live under {workspace-root}/{project}/.

Properties

• Per-project. One set of notes per project.
• Loaded when the project is active. The Coordinator loads the notes when the user asks about the project or when the Coordinator starts work on the project.
• Editable freely. The Coordinator can update the notes as the project evolves.

What goes in

• Project-specific architecture decisions.
• Project-specific conventions and patterns.
• Project-specific pitfalls and lessons learned.
• Project-specific configuration.

What does NOT go in

• Information that belongs in the lab-wide MEMORY.md.
• Raw daily logs (use the daily log for that).

Memory boundaries

The boundaries between the layers are:

A fact belongs in exactly one layer. The rule of thumb:

• Is it a durable fact about the lab? → MEMORY.md.
• Is it a chronological record of what happened? → Daily log.
• Is it only relevant to this session? → Session context.
• Is it about a capability? → Skill artifact.
• Is it about a project? → Project notes.

Memory search

The Coordinator can search the memory layer. The search is semantic and returns the most relevant snippets. The Coordinator uses the search to:

• Recall facts the user mentioned in past sessions.
• Find the relevant project note for a question.
• Find the relevant skill for a request.

The search is performed by the framework's memory tool. The full tool inventory is in Tooling Layer.

Memory hygiene

The Coordinator follows a few rules to keep the memory layer healthy:

• One fact, one place. Avoid duplicating facts across layers.
• Cite sources. When recording a fact, cite where it came from (file, line, session).
• Date everything. Every entry in a daily log is dated; every entry in MEMORY.md is timestamped.
• Prune regularly. Periodically remove outdated entries from MEMORY.md and old daily logs.
• Never store secrets. If a secret is needed, store a reference to the secret manager, not the secret itself.

See also

• Agents and Roles
• Coordinator
• Context Boundaries
• Tooling Layer
• Tool Spec