Progressive Disclosure Philosophy
Relevant source files
The following files were used as context for generating this wiki page:
Progressive Disclosure in the Claude-Mem project is a context-management strategy designed to maximize token efficiency and provide layered access to persistent memory. By structuring information retrieval into distinct tiers—ranging from compact indices to full-detail observations—the system ensures that the AI agent only consumes high-token resources when necessary.
This philosophy is implemented primarily through the Model Context Protocol (MCP) search tools and the system's instruction loading mechanisms. It allows for natural language querying of project history while maintaining visibility into token costs and system performance.
Sources: README.md:164-168, README.md:189-195, CLAUDE.md:15-20
Layered Memory Retrieval
Claude-Mem utilizes a 3-layer workflow pattern for memory retrieval. This structure prevents "token bloat" by requiring the agent to filter results at a low cost before requesting high-density data.
The 3-Layer Workflow Pattern
- Search (Compact Index): The initial step provides a high-level index of past observations. Each result typically consumes ~50-100 tokens, allowing the agent to scan many potential matches without significant overhead.
- Timeline (Contextual Anchoring): Once relevant results are identified, the agent can request chronological context around those specific observations to understand the sequence of events.
- Get Observations (Full Detail): Only after identifying the exact necessary data does the agent fetch full details, which can consume ~500-1,000 tokens per result.
Sources: README.md:197-205, cursor-hooks/cursorrules-template.md:46-52
The following flowchart illustrates the decision-making process for efficient memory retrieval:
The diagram shows the transition from low-token search results to high-token detailed observations.
Sources: README.md:197-205, cursor-hooks/cursorrules-template.md:54-57
Progressive Instruction Loading
The system applies the disclosure philosophy not just to data, but to its own operational instructions. The Worker Service features a dedicated API endpoint (/api/instructions) that allows the AI to load specific documentation sections on-demand rather than injecting the entire knowledge base into every session.
Instruction Segments
The system breaks down the SKILL.md documentation into specialized topics that are retrieved only when the agent needs guidance on a specific operational area.
| Topic | Description | Source File Section |
|---|---|---|
workflow | Standard operational procedures | ## The Workflow |
search_params | Specifics on filtering and query syntax | ## Search Parameters |
examples | Reference usage patterns | ## Examples |
operation | Specific operation file content | plugin/skills/mem-search/operations/*.md |
Sources: src/services/worker-service.ts:373-395, src/services/worker-service.ts:607-620
Implementation in Tooling
The progressive disclosure philosophy is codified in the AI's internal prompts and tool definitions, ensuring the agent adheres to token-saving workflows automatically.
Tool Usage Specifications
The available MCP tools are explicitly designed to support this tiered approach:
search: Used for initial full-text queries across observations, sessions, and prompts.timeline: Used to fetch chronological context around a specific observation ID.get_observations: Used to fetch complete data; instructions mandate batching multiple IDs to optimize the call.
Sources: README.md:207-215, cursor-hooks/cursorrules-template.md:28-44
Observer Role and Token Stewardship
In plugin/modes/code.json, the "Observer Role" instructions explicitly command the agent to "spend your tokens wisely on useful observations" and to skip routine operations like empty status checks or repetitive tasks. This ensures the disclosure of information into the permanent database is also progressive and curated.
Sources: plugin/modes/code.json:96-105, plugin/modes/code.json:115-123
Summary of Significance
The Progressive Disclosure Philosophy is central to the scalability of Claude-Mem. By enforcing a tiered data flow—from the search index to context timelines and finally to detailed observations—the project enables large-scale memory persistence without exceeding the token limits of the underlying LLM models. This architecture transforms persistent memory from a simple "dump" of data into an intelligently queried knowledge base.
Sources: README.md:164-168, src/services/worker/README.md:118-125