mirror-log 0.1.8

░  ░░░░  ░░        ░░       ░░░       ░░░░      ░░░       ░░░  ░░░░░░░░░      ░░░░      ░░
▒   ▒▒   ▒▒▒▒▒  ▒▒▒▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒▒▒▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒▒▒▒
▓        ▓▓▓▓▓  ▓▓▓▓▓       ▓▓▓       ▓▓▓  ▓▓▓▓  ▓▓       ▓▓▓  ▓▓▓▓▓▓▓▓  ▓▓▓▓  ▓▓  ▓▓▓   ▓
█  █  █  █████  █████  ███  ███  ███  ███  ████  ██  ███  ███  ████████  ████  ██  ████  █
█  ████  ██        ██  ████  ██  ████  ███      ███  ████  ██        ███      ████      ██

█  ████  ██        ██  ████  ██  ████  ███      ███  ████  ██        ███      ████      ██
█  █  █  █████  █████  ███  ███  ███  ███  ████  ██  ███  ███  ████████  ████  ██  ████  █
▓        ▓▓▓▓▓  ▓▓▓▓▓       ▓▓▓       ▓▓▓  ▓▓▓▓  ▓▓       ▓▓▓  ▓▓▓▓▓▓▓▓  ▓▓▓▓  ▓▓  ▓▓▓   ▓
▒   ▒▒   ▒▒▒▒▒  ▒▒▒▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒▒▒▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒▒▒▒
░  ░░░░  ░░        ░░       ░░░       ░░░░      ░░░       ░░░  ░░░░░░░░░      ░░░░      ░░

An append-only event log for capturing thoughts, notes, and data you do not want to lose.

mirror-log is local-first, SQLite-backed, and designed to be boring in the best way: easy to inspect, easy to script, and hard to accidentally lose context.

The default build is intentionally lean: SQLite is the source of truth, direct SQL stays first-class, and optional embedding work lives behind a feature flag instead of in the core path.

Quick Start

# Add one event
mirror-log add "Overhead allocation needs review" --source journal

# Add from file
mirror-log add-file notes.md --source meetings

# Bulk import from stdin (one line = one event)
cat ideas.txt | mirror-log stdin --source ideas

# Show recent
mirror-log show --last 10

# Search full events
mirror-log search "overhead"

# Search chunked content
mirror-log search "allocation" --chunks

# Ingestion stats (total/unique/duplicates)
mirror-log stats

# Database summary
mirror-log info

# Integrity verification (hash + relational checks)
mirror-log verify

# Generate embeddings for events (optional feature)
# mirror-log embed --source journal

# Search similar events using embeddings (optional feature)
# mirror-log search-similar "overhead allocation" --limit 5

Installation

# Clone and build
git clone https://github.com/CromboJambo/mirror-log
cd mirror-log
cargo build --release

# Binary location: target/release/mirror-log

# Optional embedding commands
cargo build --release --features embedding

# Or install locally
cargo install --path .

Documentation

• User Guide - Comprehensive documentation with examples, advanced features, and best practices
• Canonical Pipeline - Formal order of operations and governance layers
• API Documentation - Library usage for programmatic access

Core Principles

• Append-only: Events are never updated or deleted
• SQLite is source of truth: Your data stays local and inspectable
• No hidden layers: Direct SQL remains first-class
• Source-aware logging: Every event tracks where it came from
• Optional enrichment: Embeddings stay outside the default build

Canonical Pipeline

Mirror-Log ingestion follows one sequence:

1. capture
2. persist
3. structure
4. enrich (human-level, via explicit structure)

The nested design structure is:

law -> principle -> right -> rule -> guideline

Data Model

Main Tables

Events Table

• id TEXT PRIMARY KEY (UUID)
• timestamp INTEGER NOT NULL (event timestamp)
• source TEXT NOT NULL
• content TEXT NOT NULL
• meta TEXT NULL
• ingested_at INTEGER NOT NULL
• content_hash TEXT NULL (SHA256 for dedupe analytics)

Chunks Table

• Stores chunked slices of event content
• Used by search --chunks and large-content workflows

Direct SQLite Access

sqlite3 mirror.db

# Query events
SELECT datetime(timestamp, 'unixepoch'), source, content
FROM events
ORDER BY timestamp DESC
LIMIT 10;

# Count by source
SELECT source, COUNT(*)
FROM events
GROUP BY source
ORDER BY COUNT(*) DESC;

# Get stats
SELECT COUNT(*) AS total,
       COUNT(DISTINCT content_hash) AS unique_events
FROM events;

# View embeddings (optional feature)
# SELECT e.id, e.content, emb.embedding
# FROM events e
# JOIN event_embeddings emb ON e.id = emb.event_id
# LIMIT 10;

Development

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test

Dependency Audit

# Compare declared, active direct, and full transitive dependency surfaces
scripts/dep-audit.sh

# Audit an optional feature path
scripts/dep-audit.sh --features embedding

# Emit a compact line for mirror-log indexing
MIRROR_LOG_INDEX=1 scripts/dep-audit.sh

# Only append a new audit event when the surface changes
scripts/log-dep-audit.sh

# Log both the default surface and optional feature paths
scripts/log-dep-audit-matrix.sh

License

AGPL-3.0-or-later. See LICENSE.