Observational Memory

Observational memory automatically converts raw session transcripts into structured, prioritized observations. Instead of manually capturing every important moment, ClawVault watches your sessions and extracts what matters — code releases, client meetings, pricing decisions, strategy pivots, and everything in between.

The Pipeline

Observer → Compressor → Reflector → Router

graph LR
 A[Session File] --> B[Observer]
 B --> C[Compressor]
 C --> D[Reflector]
 D --> E[Router]
 E --> F[Vault Categories]

1. Observer - Monitors session files for new content (including active sessions)
2. Compressor - LLM extracts key observations with priorities
3. Reflector - Applies temporal decay and deduplication
4. Router - Auto-categorizes into vault folders

Active Session Observation

Added in v2.1.0

Long-running sessions accumulate valuable context that traditional stale-session sweeps miss entirely. Active session observation solves this with incremental, threshold-based triggers.

How It Works

1. On each heartbeat, ClawVault runs a cheap stat check on all session files
2. Per-session byte cursors track how much has already been observed
3. When new content crosses a size threshold, only the delta gets compressed
4. Cursors are updated so the same content is never processed twice

Smart Thresholds

Thresholds scale with session size to avoid over-processing small sessions or under-processing large ones:

Triggers

Active observation fires automatically on:

• Heartbeat - Periodic threshold checks (cheapest path)
• Context compaction - Forces flush before context is lost
• /new command - Captures everything before session reset

Manual Usage

# Preview what would be observed
clawvault observe --active --dry-run

# Run active observation
clawvault observe --active

# Override threshold (observe everything with 1+ new bytes)
clawvault observe --active --min-new 1

# Target a specific agent
clawvault observe --active --agent myagent

Cursors are stored in .clawvault/observe-cursors.json.

Scored Importance System

Updated in v2.2.0

Observations use scored importance tags that determine routing and retention. Each observation is tagged with a type, confidence score, and importance score:

[type|c=confidence|i=importance]

Observation Types

Importance Thresholds

Importance scores determine retention and routing behavior:

Example Observations

[decision|c=0.95|i=0.9] Chose PostgreSQL over SQLite for concurrent writes
[milestone|c=0.99|i=0.85] Published clawvault@2.2.0 to npm
[relationship|c=0.8|i=0.6] Sarah prefers Slack over email for quick questions
[lesson|c=0.85|i=0.7] Async validation improves UX significantly
[fact|c=0.9|i=0.3] Build takes approximately 45 seconds

Backward Compatibility

ClawVault v2.2.0 remains backward compatible with the legacy emoji priority format. Existing observations are read correctly, and the migrate-observations command converts them to scored format:

clawvault migrate-observations

Ledger Architecture

Added in v2.2.0

Observations follow a ledger-first architecture. Raw transcripts are preserved separately from compiled observations:

vault/
└── ledger/
    ├── raw/<source>/          # Raw session transcripts
    ├── observations/YYYY/MM/DD.md  # Compiled daily observations
    ├── reflections/YYYY-WNN.md     # Weekly reflection summaries
    └── archive/                    # Archived old observations

• Raw transcripts are stored in ledger/raw/<source>/ where <source> is the channel (e.g., main, telegram-dm, discord)
• Compiled observations land in ledger/observations/YYYY/MM/DD.md (date-partitioned by year and month directories)
• Reflections are weekly summaries in ledger/reflections/YYYY-WNN.md
• Archive contains old observations excluded from search and graph traversal

Auto-Routing to Categories

The router automatically places observations in appropriate vault categories:

[decision|c=0.95|i=0.9] "Decided to use PostgreSQL over SQLite"
 → decisions/2026-02-13.md

[relationship|c=0.8|i=0.6] "Sarah prefers Slack over email for quick questions"
 → people/sarah/2026-02-13.md

[milestone|c=0.99|i=0.85] "Artemisa demo completed"
 → projects/2026-02-13.md

[milestone|c=0.99|i=0.9] "Published clawvault@2.2.0 to npm"
 → projects/2026-02-13.md

[lesson|c=0.85|i=0.7] "Learned that async validation improves UX significantly"
 → lessons/2026-02-13.md

LLM Compression

The compressor uses LLM APIs (Gemini, Anthropic, or OpenAI) to:

• Extract key moments from conversational text
• Classify observation types and assign confidence/importance scores
• Attribute actions to specific people or agents
• Deduplicate similar observations

Post-Processing Safety Net

Even when the LLM assigns incorrect scores, regex-based enforcement rules correct them:

• Version releases (published X@2.2.0) are always scored as structural importance (>= 0.8)
• Signed contracts and pricing decisions are always structural
• Deployments and infrastructure changes are always at least potential importance (>= 0.4)

Fallback Rules

When LLM APIs are unavailable, rule-based classification kicks in using pattern matching for decisions, errors, people mentions, deadlines, and project milestones.

Usage

Automatic (Recommended)

With the OpenClaw hook installed, observation happens automatically:

• Heartbeat checks session thresholds periodically
• /new flushes before session reset
• Context compaction flushes before memory is lost
• Sleep processes session transcripts on session end

# Everything below happens automatically with the hook
clawvault sleep "built user auth" --session-transcript ./session.md
clawvault wake  # Recent observations included in context

Manual Processing

# One-shot compression of a file
clawvault observe --compress session.md

# Active session observation (incremental)
clawvault observe --active

# Watch mode for real-time processing
clawvault observe --watch ./sessions/

Configuration

Control observation behavior with environment variables:

# Disable LLM compression (rules-only)
export CLAWVAULT_NO_LLM=1

# LLM provider (first available key is used)
export GEMINI_API_KEY="your-key"      # Gemini 2.0 Flash (recommended)
export ANTHROPIC_API_KEY="your-key"
export OPENAI_API_KEY="your-key"

Entity-Aware Routing

Observations mentioning people or projects route to entity subfolders:

# "Pedro suggested using Railway for deployment"
# → people/pedro/2026-02-13.md

# "Published ClawVault v2.1.0 with active observer"
# → projects/2026-02-13.md

This creates rich entity histories visible in Obsidian's graph view.

Source Labels

When observing OpenClaw sessions, each observation is tagged with its source:

This provides attribution when reviewing observations across multiple channels.

Integration with Context

Recent observations automatically inject into:

• Wake summaries - What happened recently
• Context queries - Graph-neighbor observations
• Executive summaries - LLM-generated session briefs

Deduplication

The reflector prevents observation spam:

• Normalize content (strip timestamps, whitespace)
• Compare using bigram Jaccard similarity (threshold: 0.8)
• Merge similar observations within time windows
• Preserve the most detailed version