Building Persistent Conversation Memory for Coding Agents

Claude Code now includes session resume and auto-memory capabilities, so a custom memory layer should solve a narrower problem: storing selected summaries in a format you control. This article shows an experimental local design for that purpose. It should not copy secrets or entire transcripts by default. Review the current Claude Code overview and hooks documentation before implementing it.

The Problem with Current Memory Management

Claude Code provides CLAUDE.md, auto-memory, and resumable sessions. A separate store is useful only when you need a portable summary format or a retention policy you control. The main limitations to design around are:

• Different purposes: CLAUDE.md is best for durable project instructions, not raw conversation history
• Stale summaries: Automatically captured facts can become wrong as the code changes
• Sensitive data: Transcripts may contain secrets, source code, or client information
• Scope leakage: Cross-project sharing can expose one project's context to another

The Solution: Dynamic Conversation Memory

I developed an experimental hook-based summary store. Its main pieces are:

Key Differences from Standard Memory Management

Technical Implementation

The following snippets are simplified pseudocode, not drop-in hook files. Validate event names and input fields against the current hooks reference before using them.

1. Save Interaction Hook (save_interaction.py)

def main():
    # Read hook input from stdin
    input_data = json.load(sys.stdin)

    # Parse transcript from JSONL format
    transcript_path = input_data.get("transcript_path", "")

    # Extract last user-assistant interaction
    with open(transcript_path, 'r') as f:
        lines = f.readlines()

    # Parse and save to conversation_memory.json
    interaction = {
        "timestamp": datetime.now().isoformat(),
        "user": last_user_msg,
        "assistant": last_assistant_msg,
        "project": os.getcwd()
    }

    # Smart memory management - keep last 100 interactions
    memory["interactions"].append(interaction)
    if len(memory["interactions"]) > 100:
        memory["interactions"] = memory["interactions"][-100:]

2. Restore Memory Hook (restore_memory.py)

def format_memory_context(memory):
    """Format memory into readable context for Claude"""
    context_lines = ["# Previous Conversation Memory\n"]

    # Group interactions by project
    projects = {}
    for interaction in memory["interactions"][-20:]:
        project = interaction.get("project", "Unknown")
        projects.setdefault(project, []).append(interaction)

    # Create formatted summary
    for project, interactions in projects.items():
        context_lines.append(f"\n## Project: {project}")
        for inter in interactions[-5:]:
            context_lines.append(f"**[{time_str}]**")
            context_lines.append(f"User: {user_msg}")
            context_lines.append(f"Claude: {assistant_msg}")

    return "\n".join(context_lines)

Architecture Overview

.claude/
├── hooks/
│   ├── save_interaction.py    # Stop hook
│   └── restore_memory.py      # SessionStart hook
└── memory/
    └── conversation_memory.json  # Persistent storage

Benefits of Dynamic Conversation Memory

1. Crash Recovery

Use this pattern to restore a short, selected project summary when built-in session resume is not the right fit. Restoration is best-effort: validate the saved state before continuing work.

# Session 1: Working on authentication
$ claude
> Help me implement JWT authentication
> [Session crashes]

# Session 2: Automatic restoration
$ claude
> [Restored context about JWT authentication work]
> Continue where we left off

2. Cross-Project Intelligence

Cross-project summaries should be opt-in and limited to non-sensitive conventions. Project-specific state should remain isolated.

3. Controlled Maintenance

Automatic capture reduces manual note-taking, but the store still needs retention limits, deletion controls, and periodic review.

4. Smart Memory Management

• Automatically limits to last 100 interactions per project
• Truncates long messages for efficient storage
• Groups interactions by project for organized context
• Fails gracefully without breaking Claude functionality

5. Privacy-First Design

The example writes memory locally. Whether data leaves the machine depends on the coding agent, model provider, hooks, and integrations you configure, so do not store credentials or sensitive client data without an explicit security review.

What to Measure

Evaluate the memory layer rather than assuming it helps:

• Time spent reconstructing project context
• Incorrect or stale facts restored into a new session
• Storage growth and deletion behavior
• Accidental capture of secrets or client information
• Difference versus built-in resume and auto-memory

Implementation Details

The memory storage format is optimized for both human readability and machine processing:

{
  "interactions": [
    {
      "timestamp": "2026-08-16T16:45:00.123Z",
      "user": "Help me implement user authentication",
      "assistant": "I'll help you build a JWT-based auth system...",
      "project": "/path/to/my-project"
    }
  ],
  "metadata": {
    "created": "2026-08-16T10:00:00.123Z",
    "total_interactions": 42
  }
}

Relationship to Built-in Claude Code Features

This is an independent example, not an official Claude Code feature or announced contribution. Built-in resume, auto-memory, and hooks may remove the need for parts of this design. Prefer built-in capabilities when they meet the requirement, and keep custom storage only when you need explicit ownership of the summary format and retention policy.

Getting Started

Start with built-in resume and auto-memory. If a requirement remains, capture short summaries rather than full transcripts, redact secrets, enforce a retention limit, and test restoration on a disposable project first.

The future of AI-assisted development isn't just about better models—it's about smarter memory systems that understand the continuous nature of software development work.

For current behavior, check the Claude Code overview and hooks reference.