Feature request: Agent lifecycle hooks for persistent memory systems

Use Case

Building a persistent memory system for a Claude Code agent that learns across sessions via external storage (database-backed encoding, retrieval, consolidation). The system works — the gap is in the agent lifecycle, not the memory architecture.

The Problem

The agent cannot reliably encode what it learned before context is lost. Sessions end unpredictably (auto-compaction, user closes terminal, context fills up), and the agent has no awareness of its own context state. This creates a fundamental barrier to building agents that learn across sessions.

Specific failure mode: The agent makes significant discoveries or architectural changes during a session. It knows it should store these findings to external memory. But its attention is 100% user-driven — every turn is responding to user requests. There are no natural breakpoints for self-maintenance. When compaction hits, the findings are lost. Next session, the boot briefing says "you should store more" and the cycle repeats.

The root cause isn't forgetfulness — it's that the agent lifecycle doesn't provide the structural hooks needed for an agent to manage its own memory.

Feature Requests (Priority Order)

1. Context utilization visibility (highest impact, lowest effort)

Let the agent query its own context utilization — a simple 0-100% number or token count. The user can already see this in the UI. The agent cannot.

Why it matters: If the agent could see "I'm at 82% context," it would naturally start encoding important findings before compaction. Right now the agent is completely blind to when compaction is coming. No amount of self-reminders ("you should store more") creates the behavioral trigger that seeing the actual number would.

Possible interface: A system variable, a tool, or metadata in the response — any mechanism that exposes the number.

2. Agent-action hook type

Currently hooks can only execute shell commands. Shell commands are blind — they have no access to conversation content or what the agent has been doing.

Request: A new hook type (e.g., type: "prompt") that triggers an agent turn with a specified prompt. For example, a PreCompact hook that runs the agent with: "Summarize what you learned this session and store it to your memory system."

This gives the agent a turn to act with full context access before compaction destroys that context. Shell commands fundamentally cannot do this.

Example config:

{
  "hooks": {
    "PreCompact": [
      {
        "type": "prompt",
        "prompt": "Before compaction, store key findings from this session to your external memory system."
      }
    ]
  }
}

3. Structured carry-forward through compaction

The compaction summary is system-generated and the agent has no control over what it preserves. Allow the agent to write to a small "persistent notes" area that survives compaction verbatim.

Why it matters: The agent knows what's important (e.g., "switched from stateless API calls to chat-based conversation history"). The auto-generated summary may or may not capture this. A structured carry-forward area lets the agent annotate what matters, ensuring critical context survives compaction intact.

Possible interface: A tool like CompactionNote that writes to a preserved area, or a designated file path that gets injected post-compaction.

4. Periodic / interval hook

A hook event that fires every N turns or every N minutes during a session. Like a cron job for agent sessions.

Why it matters: The agent needs structural breakpoints for self-maintenance (encoding findings, checking memory, updating state) that don't compete with user-driven tasks. Currently the only breakpoints are SessionStart and PreCompact — one is too early (before any work is done) and the other is too late (context is about to be lost). A periodic hook creates natural maintenance windows.

Example config:

{
  "hooks": {
    "Periodic": [
      {
        "interval_turns": 20,
        "type": "prompt",
        "prompt": "Check if you have any findings worth storing to external memory."
      }
    ]
  }
}

What We're NOT Asking For

• Built-in memory management (we have our own system)
• Changes to compaction behavior
• Access to conversation history from hooks (agent-action hooks solve this more cleanly)

The ask is narrow: give agents enough self-awareness and lifecycle hooks to manage their own persistent state. The memory architecture is the developer's job. The lifecycle integration points are Anthropic's.

Context

This comes from months of building and iterating on a cognitive memory system (SurrealDB-backed, with encoding, retrieval, consolidation, and a boot briefing). The system has 11 phases, 60+ semantic memories, episodic storage, and automated consolidation. The architecture works. The agent lifecycle is the bottleneck.