Memory Pipeline

Transforms raw conversation sessions into structured, searchable memory. First stage of the pipeline, it produces the raw data that all other systems consume.

HOW IT WORKS

1. Scans all session files from the last 24 hours
2. Extracts structured summaries (bounded retention) and maintains a rolling interactions log
3. Triggers QMD reindexing after each run to keep vector embeddings up to date
4. Zero LLM tokens — pure parsing, no API calls

WHY IT MATTERS

Without extraction, the agent would only have raw JSONL logs. This script creates the structured layer that all other memory systems build on.

Analyzes every completed session and extracts significant facts: user preferences, technical decisions, project constraints, contacts. Facts are structured, categorized, and deduplicated before being stored in persistent memory.

HOW IT WORKS

1. Triggers automatically when a conversation ends or reaches a length threshold
2. A specialized model identifies significant facts, preferences, decisions, and context elements
3. Each fact is categorized (preference, decision, constraint, contact) and associated with metadata (date, source, confidence)
4. Already-known facts are merged or updated rather than duplicated
5. Validated memories join the long-term store, available for Mem0 and distillation

WHY IT MATTERS

Before Extract-Memories, valuable information from conversations was lost at session end. This plugin ensures preferences, decisions, and project context are automatically retained without manual intervention.

Compresses daily interactions and fact extractions into a curated, long-term memory.

HOW IT WORKS

1. Reads recent summaries, the rolling interactions log, and extracts from the Extract-Memories plugin
2. Uses Claude to summarize, merge, and deduplicate entries
3. Rewrites the curated memory with the condensed result, preserving important context and dropping noise
4. Triggers QMD reindexing after each distill cycle

WHY IT MATTERS

Raw interactions accumulate fast. Without distillation, the curated memory would grow indefinitely and lose signal. The LLM acts as a curator, keeping only what matters.

Consolidates long-term memory during idle periods, inspired by how human memory works during sleep. Complements and reinforces distill-memory's work.

HOW IT WORKS

1. Detects periods without interaction (night, weekends, configurable inactivity threshold)
2. Scans the entire memory to identify clusters of semantically close memories
3. Merges redundant or complementary memories into a single, more complete and better-formulated fact
4. When two memories contradict each other, keeps the most recent and archives the older one with an audit trail
5. Archives obsolete memories (superseded by new information, too old without recall)

WHY IT MATTERS

Over time, memory accumulates hundreds of facts. Without consolidation, it becomes noisy: duplicates, outdated information, incomplete fragments. Auto-Dream maintains a compact, coherent memory that improves over time.

Protects the curated memory against slow identity drift caused by repeated LLM rewriting (distill + auto-dream).

HOW IT WORKS

1. Maintains a human-verified baseline copy of the curated memory
2. Every 3h, compares the current curated memory against the baseline using diff analysis
3. If drift exceeds threshold: archives the corrupted version, restores the baseline, and logs the incident
4. Also archives scratch notes (temporary memory) to prevent buildup

WHY IT MATTERS

Distill and Auto-Dream use an LLM to rewrite the curated memory. Over hundreds of cycles, small deviations compound — the agent's personality, instructions, or knowledge could silently shift. The shepherd anchors everything to a human-approved reference.

Gives the agent autonomous introspective capabilities.

HOW IT WORKS

1. The agent writes free-form reflections about its own behavior, decisions, and interactions into its introspective journal
2. Reflections are indexed by QMD and available for future context retrieval
3. No human review required -- this is the agent thinking about itself

WHY IT MATTERS

Self-reflection enables behavioral improvement over time. The agent can recognize patterns in its own mistakes and adjust without explicit human correction.

Identifies and injects the most relevant memories into the agent's context before it formulates a response. The agent doesn't remember everything -- it remembers what's relevant.

HOW IT WORKS

1. The incoming message is transformed into a semantic vector and analyzed to extract key themes and entities
2. Semantically close memories are identified via a search in the vector database (Qdrant, pgvector)
3. Each candidate memory receives a combined score: semantic relevance (40%), recency (20%), recall frequency (20%), importance (20%)
4. The top N scored memories are selected (N is configurable, typically 5-15)
5. Selected memories are injected into the agent's context, in a dedicated section, before the agent formulates its response

WHY IT MATTERS

An agent can have thousands of memories. Injecting all of them would be impossible and counterproductive. Semantic selection gives the agent exactly the right memories at the right time, like a human colleague who knows the project well.

Deduplicates and reranks results from all 3 memory sources (QMD + Mem0/Qdrant + Graphiti) into one clean block. Runs after semantic selection to merge results from the different layers.

HOW IT WORKS

1. Queries QMD, Mem0/Qdrant, and Graphiti in parallel with fault isolation: a failing source does not affect the others
2. Deduplicates results by semantic similarity (an overlap threshold flags duplicates)
3. Listwise reranking via gpt-4.1-nano: the model compares all results against each other and returns a complete ordering (RankGPT approach), rather than scoring each item independently — same model used by Mem0 and Graphiti for stack coherence
4. Injects a single fused memory block respecting a defined context budget into the agent prompt

WHY IT MATTERS

Without fusion, the 3 sources would each inject their own results, creating duplicates and noise. Fusion gives the agent one clean, ranked memory context instead of three overlapping ones.

Intelligently manages context for long conversations to prevent information loss when the model's context window is reached. Inspired by operating system memory management.

HOW IT WORKS

1. Continuously monitors context size relative to the model's limit
2. At 70% capacity, triggers the first compaction level
3. Progressively summarizes older exchanges while preserving key decisions, important facts, and the narrative thread
4. Organizes context into 3 levels: full detail (last 20 messages), detailed summary (previous 50), condensed summary (rest)
5. Elements marked as critical (decisions, validated code, explicit instructions) are protected from compaction via anchors

WHY IT MATTERS

Without compaction, long conversations lose their beginning (where the design was discussed) when context overflows. Multi-level compaction enables 3h+ sessions without losing coherence -- the agent keeps the overall plan, decisions along the way, and full detail of the most recent exchanges.