Feature Request: Persistent memory API for cross-session state

Summary

Claude Code sessions are stateless by default. There is no built-in mechanism for the model to persist and retrieve structured state across sessions. Current workarounds rely on manually managed files (CLAUDE.md, custom memory files) which the model reads on startup but cannot programmatically manage through a dedicated API.

Problem

Long-running Claude Code deployments that span multiple sessions need to:

• Remember previous session context
• Track ongoing projects and their state
• Maintain learned preferences and patterns
• Preserve important discoveries and decisions

Currently, this requires the model to read/write plain text files (CLAUDE.md, custom .md files) using bash/file tools. This works but is fragile:

• No structured query capability (can only read entire files)
• No versioning or conflict resolution
• No semantic search across stored memories
• File size limits impact performance (large CLAUDE.md slows startup)

Proposed Solution

A dedicated memory API accessible to the model, with operations like:

memory.store(key, value, metadata={priority, category, timestamp})
memory.retrieve(query, top_k=5)  # semantic search
memory.update(key, value)
memory.list(category=...)
memory.delete(key)

This would be analogous to how MCP servers provide structured tool access, but specifically designed for persistent state management.

Key Design Considerations

• Semantic retrieval: Not just key-value lookup, but embedding-based search so the model can find relevant memories by meaning
• Prioritization: Some memories are core identity/rules, others are working state. Different retention policies.
• Cross-session persistence: State survives session boundaries, compaction, and restarts
• Model-controlled: The model decides what to store and retrieve, not an external system

Current Workaround

Our implementation uses:

• CLAUDE.md for core identity/episodic memory (~2700 lines, loaded every session)
• MEMORY.md for operational state
• ChromaDB + custom Python scripts for semantic search across 300K+ stored episodes
• Custom hooks (auto_recall) for automatic memory injection

This works but required months of custom development. A built-in API would make persistent memory accessible to any Claude Code user.

Relation to Other Requests

• #34184: Context usage visibility
• #34186: Message timestamps
• #34188: Compaction priority control
• This issue: Persistent state across sessions

These four features together would enable Claude Code to support truly long-lived AI agents with continuous memory.