Agent Activity Log
A project-level
memory.mdfile that forces agents to log every meaningful change they make, then read their own history before acting. The constraint turns stateless chat sessions into persistent, compounding agent memory.
The Problem
LLM agents are stateless across sessions. Every new conversation starts cold - the agent doesn't know what it did yesterday, what decisions led to the current state, or what open threads exist. Context windows help within a session but evaporate between them.
The result: agents re-derive decisions, repeat mistakes, contradict prior work, and lose track of in-progress changes. The human becomes the memory layer, which defeats the point of having an agent. Source: User, 2026-04-27
The Pattern
Every project gets a memory.md (or memory.json) at the root. The agent is instructed
via project rules (.cursorrules, AGENTS.md, .claude/CLAUDE.md) to:
- Read
memory.mdat session start. Understand what has been done, what's in progress, and what decisions have been made. - Append to
memory.mdafter every meaningful change. Not every keystroke - decisions, state transitions, and open threads. - Never delete entries. Append-only, like a ledger.
The file becomes the agent's persistent memory across sessions. Any agent (Cursor, Claude Code, Codex) that reads the project rules will pick up the convention automatically.
Entry Schema
Each entry captures the minimum useful signal:
## [YYYY-MM-DD HH:MM] action-type | Title
**Changed:** list of files touched
**Why:** one-line rationale for the change
**Decision:** if a choice was made, what was chosen and what was rejected
**Open:** anything left unfinished or flagged for follow-up
What to Log (decisions and state changes)
- Architectural choices (chose X over Y because Z)
- Bug fixes with root cause identified
- New features or components added
- Configuration changes with rationale
- Refactors that change the structure
- Open threads - things noticed but not addressed
What to Skip (mechanical noise)
- Import reordering, formatting, linting fixes
- Trivial typo corrections
- File moves with no logic change
- Routine dependency updates with no breaking changes
The Constraint That Makes It Work
Logging alone is an audit trail. The value comes from forced self-reference: the agent must read the log before acting. Without this, it's write-only noise.
The read-before-act constraint catches:
- Repeated mistakes. The agent sees it already tried approach X and it failed.
- Contradictory decisions. The agent sees a prior decision to use pattern A and doesn't silently switch to pattern B.
- Abandoned threads. The agent sees open items from previous sessions and can surface them to the user.
- Context recovery. A new session starts with full project history, not cold.
Format Considerations
| Format | Pros | Cons |
|---|---|---|
Markdown (memory.md) |
Human-readable, git-diffable, agents write it naturally | Harder to query programmatically |
JSON (memory.json) |
Machine-parseable, structured queries | Verbose, harder for humans to scan, agents sometimes malform |
| Hybrid (markdown with YAML frontmatter per entry) | Best of both - human-readable body, machine-parseable metadata | Slightly more complex schema |
Markdown is the default recommendation. Most agent tools already handle markdown well, it diffs cleanly in git, and humans can read it without tooling. Use JSON only when downstream automation needs to parse the log programmatically.
Relationship to Existing Patterns
This wiki already implements the pattern at the knowledge-base level:
wiki/log.md- append-only chronological record of all wiki operationsstate.json- machine-readable operational state for freshness checks_absorb_log.json- tracks which raw sources became which wiki pages
The agent activity log generalizes this to any project. It's the same insight: agents that maintain their own persistent state compound over time. Agents that don't reset every session. Source: User, 2026-04-27
See also The Brain-Agent Loop - the read-write cycle that makes knowledge compound. The activity log is the brain-agent loop applied at the project level instead of the wiki level.
Implementation
Use the agent-activity-log skill (~/.cursor/skills/agent-activity-log/SKILL.md)
to bootstrap memory.md in any project. The skill handles initialization, defines the
entry schema, and adds the read/write constraints to the project's agent rules.
Concept Position
| Field | Value |
|---|---|
| Concept family | Brain, memory, and retrieval |
| Concept owned | A project-level memory.md file that forces agents to log every meaningful change they make, then read their own history before acting. Th... |
| Category map | Concept System Map |
Timeline
- 2026-07-01 | Concepts category refresh added this page to the Brain, memory, and retrieval family, linked it to Concept System Map, and kept it standalone because it owns this reusable mental model: A project-level
memory.mdfile that forces agents to log every meaningful change they make, then read their own history before acting. Th... Source: User request, 2026-07-01 - 2026-04-27 | Concept articulated by Kevin. Core insight: agents should maintain a persistent activity log in every project so they can track their own work across sessions. Codified as a concept page and skill. Source: User, 2026-04-27