Lesson 16: Q&A (Part 1) Architecture & Data Flow Deep Dive

⏱ Est. reading time: 10 min Updated on 5/7/2026

Scenario: As the official conclusion and supplement to the "Claude-Mem Complete Practical Guide," we have compiled the most frequent hardcore technical questions. This issue focuses on answering the underlying logic of architecture design, data consistency, and the runtime environment.

Q1: Workspace Context Separation

Q: How does Claude-Mem distinguish memory contexts between different projects (Workspaces)? Will there be conflicts if I open different projects in two terminals simultaneously?

A: Absolutely no conflicts.

Claude-Mem cleverly uses an "execution path hashing" strategy. Whenever a Claude Code lifecycle hook is triggered, the system retrieves the current terminal working directory (cwd, e.g., /Users/eric/work/blog) and calculates it as a unique workspace_id (usually a hash string).

All Observations, Timelines, and Metadata are forced to carry this workspace_id as a foreign key when saved to the underlying SQLite and ChromaDB.

When you initiate a search() query in Project A, the retrieval layer automatically and implicitly appends a WHERE workspace_id = 'A' filter condition. Therefore, when running different projects concurrently across multiple terminals, the data is completely physically isolated.

Q2: Database Consistency

Q: How do SQLite (structured data) and ChromaDB (vector data) maintain consistency? How do I recover if one of the files gets corrupted?

A: Claude-Mem adopts a "SQLite as Single Source of Truth" architecture strategy.

Every time a memory is written:

  1. First, it writes to SQLite (extremely fast, supports ACID transactions).
  2. Upon success, it asynchronously submits the extracted text to the Embedding model.
  3. After retrieving the vectors, it inserts them into ChromaDB.

If a sudden power outage corrupts the ChromaDB vector database, or if you feel search accuracy has degraded, the recovery process is very simple. Since SQLite contains all the original text data, you just need to delete the corrupted vector directory and trigger a rebuild:

# 1. Delete the vector data directory
rm -rf ~/.claude-mem/chroma/

# 2. Read text fully from SQLite and regenerate Embeddings
npx claude-mem rebuild-index

The system will silently complete the consistency repair in the background without affecting your normal development.

Q3: Runtime Selection (Bun vs Node.js)

Q: Why was Bun chosen for the underlying Worker Service instead of the more mature Node.js or higher-performance Rust?

A: This is a decision balancing distribution cost and background daemon performance:

  1. Extreme cold start and ultra-low resident memory: The Worker is a service residing silently in the background (Port 37777). Bun outperforms Node.js in memory fragmentation management and startup speed, making it more suitable as a lightweight local daemon.
  2. Out-of-the-box ultra-fast SQLite bindings: Bun has bun:sqlite built-in, which directly uses highly optimized C API bindings. Using SQLite in Node.js usually requires compiling node-sqlite3 (often encountering node-gyp errors) or using a mediocre wasm solution. Bun increases database read/write speeds by 3-5 times without requiring users to configure local C++ compilation environments.
  3. Native TypeScript support: No extra tsc compilation steps or ts-node needed, reducing CLI distribution complexity and cold start times.

Q4: Offline & Retries (Async Summarization)

Q: What happens to the asynchronous summarization mechanism when it encounters LLM API rate limits (429) or network disconnections? Will data be lost?

A: No data will be lost.

Claude-Mem designed a robust mechanism similar to a database WAL (Write-Ahead Log). The original conversation history (Raw Transcript) is immediately and losslessly flushed to the local sequence table (Queue Table).

The Worker opens a consumption queue in the background:

  • On 429 error: Triggers an Exponential Backoff strategy, waiting for 2s, 4s, 8s... before retrying the extraction.
  • On network disconnect: Tasks remain in the queue, marked as pending.
  • Shutdown/Restart: Since data is already flushed to disk, the next time the Worker starts up, it will read the pending records from the database during its self-check phase and continue completing LLM summaries and vectorizations.

Q5: [Mermaid Sequence Diagram] Hook Flow Panorama

Q: What is the complete flow from triggering the on_turn_end hook in the terminal to the Worker finally writing memories to the database?

A: This is a complex chain involving local scripts, HTTP communication, and asynchronous LLM calls. The specific process is as follows:

sequenceDiagram
    participant User as User (Terminal)
    participant CC as Claude Code
    participant Hook as Local Hook Script
    participant Worker as Bun Worker (37777)
    participant DB as SQLite / Chroma
    participant LLM as LLM API (Gemini/Claude)

    User->>CC: Input prompt and execute
    CC->>Hook: Trigger on_turn_end (passing transcript)
    Hook->>Worker: POST /api/observations (Pass raw logs)
    
    rect rgb(236, 253, 245)
        Note right of Worker: Fast Path (Millisecond response)
        Worker->>DB: 1. Save raw logs to Pending queue table
        Worker-->>Hook: 200 OK (Release user terminal)
    end
    Hook-->>CC: Hook execution finishes, waits for next input
    
    rect rgb(254, 252, 232)
        Note right of Worker: Slow Path (Background async processing)
        Worker->>LLM: 2. Request summarization (Context Engineering)
        LLM-->>Worker: Return structured JSON (Summary, Tags, Entities)
        Worker->>DB: 3. Update SQLite (Save as formal Observation)
        Worker->>LLM: 4. Request Embeddings (Vectorization)
        LLM-->>Worker: Return float32 array
        Worker->>DB: 5. Write to ChromaDB
        Worker->>DB: 6. Mark Pending task as Completed
    end

Illustration: Because of the Fast Path, no matter how slow the background LLM summarization is, your terminal will never get stuck.

Q6: Retrieval Omissions (Progressive Disclosure Blind Spots)

Q: Why does Progressive Disclosure sometimes "fail to find" historical code snippets that clearly exist in the database?

A: This is usually caused by "Semantic Dispersion" or "Token Budget Filtering".

  1. Semantic Dispersion (Layer 1 Omission): Vector retrieval is based on semantics. If you search for a specific variable name userId_v2, but the summary saved at the time was "Refactored authentication module," the semantic distance might be too far, pushing it out of the Top K.
  2. Summary Over-folding (Layer 2 Misjudgment): Even if Layer 1 finds it, during the summary expansion phase, the AI might think "Refactored authentication module" cannot solve your specific Bug, thus deciding to skip triggering Layer 3 (reading raw long text), causing the code snippet to remain "invisible."

💡 Fixes:

  • Precise Instructions: Forcefully guide in the prompt, e.g., "Use the search tool, forcefully query the keyword userId_v2, and set the limit to 20 all at once."
  • Direct Access: If you remember the approximate time or ID, use get_observations([id]) to directly bypass defenses and read underlying data.

Q7: Cache Maintenance (Vector DB Maintenance)

Q: As project iterations progress and deprecated code piles up, how do I manually clean or rebuild the local ChromaDB vector cache to prevent interference from old logic?

A: Vector pollution from deprecated (Dead) Code is inevitable in long-lifecycle projects. You can perform active "forgetting" through these steps:

  1. Soft Deprecation (Recommended): Use Make Plan + Do to find observation_ids related to deprecated modules, then use MCP calls to tag them with deprecated: true metadata. The retrieval layer will lower the weight of these data during filtering.
  2. Pruning by Timeline:
    # Clean up early exploration records before Jan 1, 2024
npx claude-mem prune --before "2024-01-01"
  3. Nuke-level Rebuild: If the project underwent a massive refactoring (like migrating from Vue to React), it's recommended to clear the vector DB and use the current, latest codebase to generate a new architectural snapshot. This is much more efficient than keeping messy transitional histories.

Next Issue Preview: In Lesson 17, we will dive into Skills and MCP Troubleshooting, answering high-frequency connection errors like "Connection Refused" and providing a checkpoint pullback solution for resolving major goal deviations.