Implicit Memory System

This is a research tool made by AlteredCraft

This is a demonstration app showing use of Claude's autonomous memory management using Anthropic's Memory Tool. Claude decides what to remember from your conversations and manages its own persistent memory across sessions - no explicit commands needed.

Related Articles:

• The Memory Illusion: Teaching Your LLM to Remember
• Implicit Memory Systems for LLMs

---

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Anthropic API key (get one here)

Setup

# 1. Install dependencies
npm install

# 2. Configure your API key (optional - can also set in UI)
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# 3. Run the app
npm run dev
# Open http://localhost:3000

---

✨ Features

🌐 Modern Web Interface

• Real-time streaming chat - See Claude's responses as they're generated
• Memory file browser - Visual explorer for Claude's memory files
• Session history - Review past conversations with token usage stats
• Sequence diagrams - Generate Mermaid diagrams from session traces
• System prompt selection - Choose from different assistant personalities

🧠 Autonomous Memory Management

Claude decides what to remember during natural conversations:

Example:

You: Hi, I'm Alex. My son Leo turns 5 next Tuesday.
Claude: Hi Alex! Nice to meet you. Happy early 5th birthday to Leo!
         [Creates /memories/user_profile.txt]

# Later...
You: What gift ideas do you have?
Claude: For Leo's 5th birthday, here are some age-appropriate ideas...
        [Recalls Leo's age from memory]

How it works:

1. You chat naturally - No special commands needed
2. Claude decides what to remember - Names, preferences, project details
3. Memory persists - Stored as text files in ./memories/
4. Automatic recall - Claude retrieves relevant memories when needed

📊 Session Recording & Analysis

• Every conversation traced to ./sessions/ as JSON
• Full observability: messages, tool calls, token usage
• Generate visual sequence diagrams showing interaction flow
• Export and analyze conversation patterns

---

🏗️ Architecture

Single Next.js Full-Stack Application:

• Frontend: Next.js 16 + TypeScript + Tailwind CSS
• Backend: Next.js API Routes (server-side TypeScript)
• Communication: Server-Sent Events (SSE) for streaming
• Storage: Local filesystem for memory files and sessions
• AI: Anthropic Claude with Memory Tool integration

Key Components:

• ConversationManager - Orchestrates Claude conversations
• LocalFilesystemMemoryTool - File-based memory storage
• SessionTrace - Records all interactions for analysis
• 14 API Routes - Session, chat, memory, and history management

See CLAUDE.md for detailed architecture documentation.

---

🎨 System Prompts

Choose from different assistant personalities in the UI settings:

prompts/
├── concise prompt_explanatory.txt       # Verbose memory logging
├── concise prompt.txt                   # Standard behavior
├── more precise prompt_explanatory.txt  # Detailed explanations
└── more precise prompt.txt              # Fine-tuned responses

Custom Prompts:

• Create .txt files in prompts/ directory
• They'll automatically appear in the UI selector
• Lines starting with # are comments (stripped automatically)
• Current date/time appended automatically

---

📊 Session Traces & Diagrams

Every conversation is recorded with complete observability:

{
  "session_id": "20250117_143022_abc123",
  "start_time": "2025-01-17T14:30:22Z",
  "model": "claude-sonnet-4-5-20250929",
  "events": [
    {"event_type": "user_input", "content": "..."},
    {"event_type": "tool_call", "tool_name": "memory", "command": "create"},
    {"event_type": "llm_response", "content": "..."},
    {"event_type": "token_usage", "cumulative": {...}}
  ]
}

Generate Sequence Diagrams:

1. View any session in the UI
2. Click "Generate Diagram"
3. See Mermaid visualization of interaction flow

---

📚 Learn More

• Article: Implicit Memory Systems for LLMs : When Code Surrenders to Context
• Anthropic Docs: Memory Tool
• Architecture Details: CLAUDE.md - Comprehensive technical documentation
• Original v1: simple_llm_memory_poc

---

🔧 Appendix: Memory Tool Implementation

The LocalFilesystemMemoryTool class implements Anthropic's Memory Tool API with a custom filesystem-based storage system. Located at lib/server/memory-tool.ts, it provides Claude with six autonomous memory operations for persistent, file-based memory management.

The Six Operations

• view - Read files or list directory contents
• create - Create new memory files (prevents overwrites)
• str_replace - Find and replace text within files
• insert - Insert text at specific line numbers
• delete - Remove files or directories recursively
• rename - Move or rename files/directories

Key Features

• Path validation - Prevents directory traversal attacks via _validatePath() method
• Dual logging - MemoryOperationLogger (./logs/memory-operations.log) + console output
• Session tracing - All operations logged to session JSON files
• Real-time UI updates - Operation tracking powers MemoryBrowser animations
• Integration - Registered with ConversationManager and Anthropic's toolRunner

Storage & Organization

Memory files are stored in ./memories/ as plain text. Claude autonomously decides the file structure (flat or hierarchical) and naming conventions.

Implementation Files

• lib/server/memory-tool.ts - Main implementation (618 lines)
• lib/server/conversation-manager.ts - Tool instantiation and integration
• lib/server/memory-operation-logger.ts - Dedicated logging system
• lib/server/session-trace.ts - Session recording and tracing

For detailed documentation, see CLAUDE.md.

---

🔧 Appendix: Real-Time Memory Activity Signaling

The UI displays memory operations in real-time as Claude executes them, creating responsive visual feedback through the Memory Tool Calls console and file browser animations.

The Challenge

Tool call events are generated via callbacks during SDK execution, but callbacks cannot directly yield values in async generators. Initially, events were accumulated in an array and only emitted after each message stream completed, causing all memory operations to appear batched at the end of responses.

The Solution: AsyncEventQueue

A lightweight synchronous queue bridges the callback-to-generator gap:

• AsyncEventQueue (lib/server/async-event-queue.ts) - 71-line queue with enqueue() (callback-safe) and drain() (generator-safe) methods
• Frequent draining - Queue checked after every SDK streaming event (~50ms intervals)
• Multi-layered - Additional drains after message completion, before done event, and in error handlers

Technical Flow

Memory Tool Executes → SessionTrace callback → eventQueue.enqueue(event)
                                                         ↓
SDK streaming event arrives → drainEventQueue() → yield to SSE stream
                                                         ↓
Frontend receives → ToolCallConsole + MemoryBrowser update immediately

Result

Memory operations appear in the UI within <50ms of execution with word-by-word text streaming preserved. The queue is drained after each content_block_delta event, ensuring tool calls are never batched even when they execute before text generation.

Implementation: lib/server/conversation-manager.ts:64-134