ADR-021: Context Query System (/cxq) - Anti-Forgetting Memory Architecture

Status

ACCEPTED (2025-12-10, Updated 2026-02-03)

Context

Problem Statement

After extracting session data via /cx (ADR-020), users need to:

1. Search messages across all sessions and LLM providers
2. Query knowledge (decisions, patterns, error solutions)
3. Analyze usage (tokens, tools, costs)
4. Filter by source (Claude vs Codex vs Gemini)
5. Retrieve context for RAG-style recall

A unified query interface is needed that abstracts the four-tier database architecture (ADR-118) while providing powerful search capabilities.

Database Architecture

The query system operates across four databases:

Tier	Database	Content	Query Types
1	platform.db	Components (agents, skills, commands)	Component search, self-awareness
2	org.db	Decisions, skill learnings, error solutions	Knowledge queries
3	sessions.db	Messages, tool analytics, token economics	Message search, analytics
4	projects.db	Project metadata, embeddings	Project-scoped search

Decision

Implement /cxq as a unified context query interface with:

1. Query Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      /cxq QUERY SYSTEM                           │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   FTS5 Search   │ │ Semantic Search │ │  RAG Retrieval  │
│  (Full-Text)    │ │  (Embeddings)   │ │    (--recall)   │
└─────────────────┘ └─────────────────┘ └─────────────────┘
              │               │               │
              └───────────────┼───────────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  platform.db    │ │    org.db       │ │  sessions.db    │
│   (Tier 1)      │ │   (Tier 2)      │ │   (Tier 3)      │
│  Components     │ │  Knowledge      │ │  Messages       │
└─────────────────┘ └─────────────────┘ └─────────────────┘

2. Search Capabilities

FTS5 Full-Text Search

-- SQLite FTS5 for instant text search
SELECT * FROM messages_fts
WHERE messages_fts MATCH 'error AND authentication'
ORDER BY rank;

Syntax supported:

• word1 word2 - Both words (AND)
• word1 OR word2 - Either word
• "exact phrase" - Phrase match
• word* - Prefix match
• NEAR(a b, 5) - Proximity search
• -word - Exclude word

Semantic Search

# Vector similarity using embeddings
results = semantic_search(
    query="how to fix authentication",
    threshold=0.3,
    limit=20
)

RAG Retrieval

# Combines: messages + decisions + patterns + errors
/cxq --recall "database migration"

3. Query Categories

Tier 1: Component Queries (platform.db)

/cxq --components              # List all components
/cxq --components "database"   # Search components
/cxq --component-type agent    # Filter by type
/cxq --component-semantic "intent"  # Semantic search

Tier 2: Knowledge Queries (org.db)

/cxq --decisions               # List decisions
/cxq --decisions --decision-type architecture
/cxq --patterns --language python
/cxq --errors "TypeError"
/cxq --learnings               # Skill learnings

Tier 3: Session Queries (sessions.db)

# Message search
/cxq "search term"             # FTS5 search
/cxq --recent 20               # Recent messages
/cxq --today                   # Today's messages
/cxq --role assistant          # Filter by role

# LLM filtering (ADR-122)
/cxq "error" --llm claude      # Claude only
/cxq --by-llm                  # Breakdown by LLM

# Analytics
/cxq --tokens                  # Token usage
/cxq --cost                    # Cost analysis
/cxq --tools                   # Tool analytics
/cxq --activities              # Component invocations

Tier 4: Project Queries (projects.db)

/cxq --projects                # List projects
/cxq --project <name> "query"  # Project-scoped search

4. Multi-Database Search

For cross-database queries, use Reciprocal Rank Fusion (RRF):

/cxq "authentication" --multi-db

RRF Algorithm:

def reciprocal_rank_fusion(result_lists, k=60):
    """Merge results from multiple databases"""
    scores = {}
    for result_list in result_lists:
        for rank, doc in enumerate(result_list):
            scores[doc.id] = scores.get(doc.id, 0) + 1 / (k + rank)
    return sorted(scores.items(), key=lambda x: x[1], reverse=True)

5. Database Views

18 pre-built views for common queries:

View	Purpose
knowledge_stats	Row counts for all knowledge tables
recent_decisions	High-confidence decisions (7 days)
error_frequency	Most common errors with counts
patterns_summary	Code patterns by language
session_summary	Session activity and durations
component_overview	Components by type/status
today_activity	Last 24 hours activity

Implementation

Command Interface

# Basic search
/cxq "query"                   # FTS5 search
/cxq --semantic "query"        # Semantic search
/cxq --recall "topic"          # RAG retrieval

# Filters
/cxq "query" --llm claude      # LLM filter
/cxq "query" --role user       # Role filter
/cxq "query" --today           # Date filter
/cxq "query" --code            # Code only

# Knowledge
/cxq --decisions               # Decisions
/cxq --patterns                # Code patterns
/cxq --errors                  # Error solutions

# Analytics
/cxq --tokens                  # Token usage
/cxq --cost                    # Cost breakdown
/cxq --tools                   # Tool analytics

# Output
/cxq "query" --json            # JSON output
/cxq "query" --full            # Full content
/cxq "query" --limit 50        # Limit results

Scripts

Script	Purpose
scripts/context-query.py	ADR-118 compliant (primary)
scripts/context-db.py	Legacy (deprecated, advanced features)

Query Routing

def route_query(query_type):
    """Route queries to appropriate database"""
    routing = {
        'messages': 'sessions.db',      # Tier 3
        'decisions': 'org.db',          # Tier 2
        'skill_learnings': 'org.db',    # Tier 2
        'error_solutions': 'org.db',    # Tier 2
        'components': 'platform.db',    # Tier 1
        'projects': 'projects.db',      # Tier 4
        'token_economics': 'sessions.db', # Tier 3
        'tool_analytics': 'sessions.db',  # Tier 3
    }
    return routing.get(query_type)

Future Evolution (ADR-149)

The query system will evolve through three phases:

Phase 1: Enhanced Flags (Current + Planned)

/cxq --where "confidence > 0.8 AND decision_type = 'api'"
/cxq --group-by model,week
/cxq --traversal invokes:2

Phase 2: Query Templates

/cxq --query high-cost-sessions
/cxq --queries  # List templates

Phase 3: Optional DSL (If Needed)

FROM decisions d
WHERE d.confidence > 0.7
  AND d.created_at > @recent(7d)
ORDER BY d.confidence DESC
LIMIT 20

Consequences

Positive

1. Unified interface - Single command for all queries
2. Multi-tier abstraction - Users don't need to know database details
3. Powerful search - FTS5, semantic, and RAG capabilities
4. LLM filtering - Query by source provider
5. Analytics - Token, tool, and cost analysis built-in

Negative

1. Complexity - Many options to learn
2. Performance - Multi-database queries can be slow
3. Migration - Legacy context-db.py still needed for some features

Mitigations

• Progressive disclosure - Simple queries are simple
• RRF optimization - Parallel database queries
• Feature migration - Moving features to context-query.py (J.16)

Integration Points

System	Integration
/cx (ADR-020)	Extracts data that /cxq queries
/orient	Uses /cxq --recent for session context
/recall	Alias for /cxq --recall
BI Dashboard	Uses /cxq for data queries
MCP Servers	Expose /cxq capabilities via MCP

Files

File	Purpose
scripts/context-query.py	Primary query script (ADR-118 compliant)
scripts/context-db.py	Legacy script (deprecated)
commands/cxq.md	Command documentation
schemas/cusf-v1.0.0.json	CUSF schema for query results

Related

• ADR-020: Context Extraction System (/cx)
• ADR-118: Four-Tier Database Architecture
• ADR-114: User Data Separation
• ADR-122: Unified LLM Architecture
• ADR-148: Database Schema Documentation Standard
• ADR-149: Query Language Evolution Strategy

Changelog

Date	Change
2025-12-10	Initial version
2026-01-28	Added LLM filtering (ADR-122)
2026-01-28	Added Tier 3 analytics queries (J.16)
2026-02-03	Documented as formal ADR (was referenced but not created)

---

Track: J (Memory Intelligence) Command: /cxq Script: scripts/context-query.py