InkdownInkdown
Start writing

Claude-Code

62 files·4 subfolders

Shared Workspace

Claude-Code
codex

memory-system

Shared from "Claude-Code" on Inkdown

Claude Code Memory Architecture

Based on everything explored in the source code, here’s the full technical recipe behind Claude Code’s memory architecture. alt

Shared by Claude Code

Claude Code’s memory system is actually insanely well-designed. It is not a “store everything” system. It is constrained, structured, and self-healing memory.

The architecture is doing a few very non-obvious things:

1. Memory = Index, Not Storage

  • MEMORY.md is always loaded, but it is just pointers, roughly ~150 characters per line.
0000_start_here_index_and_recommended_reading_order.md
0100_project_overview_tech_stack_runtime_modes_and_folder_map.md
0200_startup_flow_entry_points_and_cold_start_sequence.md
0300_codebase_modules_layers_state_models_and_schemas.md
0400_system_architecture_and_design_rationale.md
0500_interactive_repl_request_flow_end_to_end.md
0600_headless_sdk_and_print_mode_request_flow_end_to_end.md
0700_mcp_integration_connection_and_tool_call_flow.md
0800_external_services_sdks_storage_and_local_dependencies.md
0900_environment_variables_settings_feature_flags_and_failure_modes.md
1000_non_obvious_patterns_gotchas_and_debugging_traps.md
1100_full_codebase_file_inventory_grouped_by_directory.md
kimi
00-overview.md
01-entrypoints.md
02-state-management.md
03-query-system.md
04-tools-system.md
05-tasks-system.md
06-ui-components.md
07-bridge-remote.md
08-services.md
09-skills-plugins.md
10-commands.md
11-testing-architecture.md
12-permission-system.md
13-build-system.md
14-ink-internals.md
15-git-internals.md
16-context-compaction.md
17-vim-mode.md
18-mailbox-notifications.md
19-session-persistence.md
20-hooks-system.md
21-error-recovery.md
README.md
qwen
00-overview.md
01-entry-points.md
02-query-engine.md
03-tools-and-tasks.md
04-commands-and-skills.md
05-state-management.md
06-ink-rendering.md
07-bridge-remote.md
08-mcp-services.md
09-services-overview.md
10-multi-agent.md
11-system-prompt-constants.md
12-tool-interface.md
13-memory-system.md
14-buddy-companion.md
15-keybindings.md
16-stop-hooks.md
17-vim-mode.md
18-upstreamproxy.md
19-cost-tracking-history.md
20-contexts-styles-onboarding.md
21-hooks.md
22-screens.md
tweets-explain
claude-code-memory-analysis.md
compact
memory-system
agentic-architecture
  • Actual knowledge lives outside and is fetched only when needed.

    • 2. Three-Layer Design (Bandwidth-Aware)

    • Index → always loaded
    • Topic files → loaded on demand
    • Transcripts → never fully read, only grep’d

    3. Strict Write Discipline

    • Write to file first, then update the index
    • Never dump full content into the index
    • This prevents entropy and context pollution

    4. Background “Memory Rewriting” (autoDream)

    • Merges related memories
    • Dedupes repeated information
    • Removes contradictions
    • Converts vague statements into absolute ones
    • Aggressively prunes stale or low-value memory
    • Memory is continuously edited, not endlessly appended

    5. Staleness Is First-Class

    • If memory does not match reality, memory is wrong
    • Code-derived facts are never stored
    • The index is forcibly truncated to stay fresh and useful

    6. Isolation Matters

    • Consolidation runs inside a forked subagent
    • Tool access is limited
    • This reduces the risk of corrupting the main context

    7. Retrieval Is Skeptical, Not Blind

    • Memory is treated as a hint, not ground truth
    • The model is expected to verify memory before using it

    8. What They Do Not Store Is the Real Insight

    • No debugging logs
    • No code structure snapshots
    • No PR history
    • If something is derivable, it should not be persisted