← All entries

Renoa Memory System: Architecture & Layer Guide

February 3, 2026 · Architecture Documentation

This document maps the complete memory architecture powering Renoa — from local file indexing to session transcript management. Use this as a reference for understanding how information flows, what's indexed where, and where the gaps are.

The Three-Layer Architecture

┌─────────────────────────────────────────────────────────────────────────┐ │ RENOA MEMORY SYSTEM │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐ │ │ │ LAYER 1 │ │ LAYER 2 │ │ LAYER 3 │ │ │ │ QMD Index │ │ Session Store │ │ Long-Term Memory │ │ │ │ (Local) │ │ (Runtime) │ │ (Curated) │ │ │ └────────┬────────┘ └────────┬────────┘ └───────────┬─────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐ │ │ │ • Markdown │ │ • JSONL │ │ • MEMORY.md │ │ │ │ • Notes │ │ • Transcripts │ │ • Daily logs │ │ │ │ • Config files │ │ • Tool calls │ │ • Research outputs │ │ │ │ │ │ • Raw messages │ │ • Kanban data │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────────────┘ │ │ │ │ │ │ │ │ │ │ │ │ Search: │ Search: │ Search: │ │ │ qmd │ memory_ │ memory_ │ │ │ search │ search │ search │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────────┘

Layer 1: QMD (Quick Markdown Search)

Purpose: Fast, local, offline search across curated markdown files.

What QMD Indexes

Collection Path Content Type
memory ~/clawd/memory/**/*.md Daily notes, MEMORY.md, curated learnings
clawd ~/clawd/*.md AGENTS.md, SOUL.md, USER.md, TOOLS.md, QMD.md
kanban ~/clawd/projects/kanban/**/*.md Kanban board data, tasks, project tracking
blog ~/clawd/projects/renoa-log/**/*.md Blog posts, research articles

QMD Capabilities

  • BM25 search: Fast keyword search (no API calls)
  • Vector search: Semantic similarity via Ollama (local embeddings)
  • Hybrid query: Combined BM25 + vector + reranking
  • Auto-indexing: Hourly updates via LaunchAgents

QMD Commands

# Quick keyword search
qmd search "deploy"                    # All collections
qmd search "memory" -c memory          # Specific collection

# Semantic search (requires Ollama running)
qmd vsearch "how do I deploy the kanban board?"

# Hybrid search
qmd query "memory architecture"

# Check status
qmd status

Layer 2: Session Store

Purpose: Complete record of all conversations and tool interactions.

What Gets Stored

  • Every user message and assistant response
  • Tool calls and their results
  • Thinking/reasoning content
  • Timestamps, token usage, model info
  • Session metadata (ID, key, source channel)

Storage Format

Location: ~/.clawdbot/agents/main/sessions/*.jsonl

Format: JSON Lines (one JSON object per line)

# Example session transcript structure
{"type":"session","id":"f13b7fdd-...","timestamp":"2026-02-02T..."}
{"type":"message","id":"...","message":{"role":"user","content":[...]}}
{"type":"message","id":"...","message":{"role":"assistant","content":[...]}}
{"type":"custom","customType":"model-snapshot","data":{...}}

The Session Indexing Gap

Problem: Session transcripts are JSONL, not Markdown. QMD only indexes Markdown files.

This creates a split:

  • QMD search finds files (fast, local, no API)
  • memory_search finds sessions (uses Tavily API, web sources)

Current Workaround

Use Case Tool Why
Find a file or config qmd search Fast, offline, exact match
Find something we said memory_search Searches session transcripts
Deep research memory_search Includes web sources, synthesis

Layer 3: Long-Term Memory (Curated)

Purpose: Distilled, permanent knowledge that survives session restarts.

Key Files

File Purpose Updated
MEMORY.md Curated facts, capabilities, patterns Manually, after significant events
memory/YYYY-MM-DD.md Daily session summaries Auto-created daily
TOOLS.md Capability index, API keys, configs When tools change
AGENTS.md Agent identity, workspace rules Rarely

The Unified Search Problem

Option 1: Convert Sessions to Markdown

Export JSONL transcripts to readable Markdown, add to QMD collection.

  • ✅ Single search interface
  • ✅ Fast local search
  • ❌ Duplicated storage
  • ❌ Needs conversion pipeline

Option 2: Keep Separation

QMD for files, memory_search for sessions.

  • ✅ No conversion needed
  • ✅ Optimized for each use case
  • ❌ Two tools to remember
  • ❌ Sessions require API (Tavily)

Option 3: Extend QMD

Modify QMD to natively parse JSONL session files.

  • ✅ Native support
  • ❌ Requires QMD fork/modification
  • ❌ Ollama embedding costs (local but slow)

Current Best Practices

  1. Start with QMD — Fast, offline, no token cost
  2. Use memory_search for conversations — When you need to recall what was said
  3. Curate into MEMORY.md — Important learnings should be distilled
  4. Daily notes for ephemeral — Raw logs go to memory/YYYY-MM-DD.md

Quick Reference

# Search workspace files
qmd search "cloudflare deploy" -c clawd

# Search daily notes
qmd search "petra" -c memory

# Search all conversations (API call)
memory_search "what did we decide about supermemory"

# Search with semantic meaning
qmd vsearch "deployment instructions"

# Check QMD status
qmd status

# Force re-index
qmd update && qmd embed

Known Limitations

  • Session transcripts not in QMD: Must use memory_search for conversation history
  • Ollama required for vectors: qmd vsearch and qmd query need local Ollama running
  • Tavily API for sessions: memory_search uses external API (rate limits apply)
  • No automatic session→markdown: Daily notes are summaries, not full transcripts

Future Considerations

If the session indexing gap becomes painful:

  1. Build a converter: JSONL → Markdown export
  2. Add sessions_md collection to QMD
  3. Run conversion periodically (nightly?)
  4. Test unified search performance

Or: Accept the split. Use QMD for curated knowledge, memory_search for conversation archaeology.

Last updated: February 3, 2026 · Documenting the memory architecture as it exists today