Summary

Agents suffer from catastrophic context loss after session compaction, making long-horizon tasks unreliable. We propose a simple solution based on hierarchical memory architecture, and a PR to fix it in core. Interim solution uses existing hooks and does not change the core repository (local markdown, exiting hooks, and forward compatible) but leverages undocumented API.

Currently, when a session approaches context limits automatic compaction triggers. Session history is summarized. Old messages are replaced with the summary and the agent resumes with compressed context.

The failure mode:* Post-compaction, the agent "wakes up" with:

• A potentially lossy summary (LLM summarization is imperfect)
• No memory of active tasks, decisions in progress, or working state
• Instructions to "read memory files" that it often ignores or competes with user instructions

Proposed solution

Memory Hierarchy for Agents

Drawing from cognitive science, effective agent memory requires multiple tiers, compatible with current hooks and markdown file system:

The default bootstrap files injected into every session are:

AGENTS.md    ← Agent instructions
SOUL.md      ← Identity/persona  
TOOLS.md     ← Tool-specific notes
IDENTITY.md  ← Quick identity reference
USER.md      ← Human context
HEARTBEAT.md ← Periodic check config
BOOTSTRAP.md ← First-run only
MEMORY.md    ← Long-term memory

What would you like Clawdbot to do?
### Implementation
Add `WORKING.md` to the `WorkspaceBootstrapFileName` type in `src/agents/workspace.ts`:
```typescript
export const DEFAULT_WORKING_FILENAME = "WORKING.md";

export type WorkspaceBootstrapFileName =
  | typeof DEFAULT_AGENTS_FILENAME
  | typeof DEFAULT_SOUL_FILENAME
  | typeof DEFAULT_TOOLS_FILENAME
  | typeof DEFAULT_IDENTITY_FILENAME
  | typeof DEFAULT_USER_FILENAME
  | typeof DEFAULT_HEARTBEAT_FILENAME
  | typeof DEFAULT_BOOTSTRAP_FILENAME
  | typeof DEFAULT_MEMORY_FILENAME
  | typeof DEFAULT_MEMORY_ALT_FILENAME
  | typeof DEFAULT_WORKING_FILENAME;  // ← Add this

And include it in the bootstrap file resolution logic.

Alternatives considered

• Core code changes break compatibility, and force solution on all users. A
• Requests are not reliable. Hook told agent "READ WORKING.md" → agent ignored post-compaction
• Plugins add middle ware and complexity.

Additional context

The Key Insight

Working memory must be injected, not read.
After compaction, the agent has no reliable way to remember to read WORKING.md. The solution is to make WORKING.md a bootstrap file — automatically injected into every session, including post-compaction sessions.
Test passed. Working memory survived compaction. Long-horizon tasks, coherence and success rates are improved.

While awaiting core changes, we implemented this via agent:bootstrap hook:

// hooks/memory-first/handler.ts
// Inject WORKING.md into bootstrapFiles array
if (!hasWorkingMd) {
  const workingPath = path.join(workspaceDir, "WORKING.md");
  const workingContent = readFileSafe(workingPath);
  if (workingContent) {
    context.bootstrapFiles.push({
      name: "WORKING.md",
      path: workingPath,
      content: workingContent,
      missing: false,
    });
  }
}

This works but relies on undocumented internal APIs.

Benefits of Core Integration

Proposed Changes

Files to Modify

1. src/agents/workspace.ts

   • Add DEFAULT_WORKING_FILENAME = "WORKING.md"
   • Add to WorkspaceBootstrapFileName union type
   • Include in loadWorkspaceBootstrapFiles() resolution

2. docs/reference/templates/WORKING.md

   • Create template file with usage guidance

3. docs/concepts/memory.md

   • Document WORKING.md purpose and best practices

Template Content

# WORKING.md — Current State
Last updated: (timestamp)
## Active Context
(Current task, project, or conversation context)
## Decisions in Progress
(Pending decisions, options being evaluated)
## Next Steps
(Immediate action items)
## Notes
(Scratchpad for session-specific information)

---

*This file is automatically injected into every session.*
*Update it frequently to maintain context across compactions.*

Migration Path

• Non-breaking: Existing workspaces without WORKING.md simply don't get it injected (missing: true)
• Opt-in: Users create WORKING.md when they want working memory
• Template: moltbot setup and wizard create WORKING.md by default

Conclusion

Adding WORKING.md to bootstrap files is a small change with significant impact on agent reliability for long-horizon tasks. It completes the hierarchical memory architecture that MEMORY.md began, giving agents both long-term and working memory.

The code word test validated this approach. Agents with injected WORKING.md maintain context across compactions — enabling tasks that span hours or days rather than single sessions.

Links, screenshots, or related issues.