meld

Deterministic context management for AI agents. Meld tracks your codebase state using Merkle trees and stores AI-generated context frames linked to each file and directory.

Why meld?

AI agents need context about your code. Traditional approaches require expensive full-codebase scans or semantic search. Meld provides:

• Instant invalidation — Hash comparison detects changes in O(1)
• Fast lookups — Retrieve context for any file without scanning
• Immutable history — Context frames are append-only and verifiable
• Multi-agent support — Multiple agents can read/write context independently

Installation

cargo install --path .

Quick Start

# Initialize meld in your project
meld init

# Scan the filesystem to build the tree
meld scan

# Check workspace status
meld status

# Generate context for the codebase
meld context generate

Core Commands

Workspace

meld scan                    # Build/rebuild the Merkle tree
meld status                  # Show workspace, agent, and provider status
meld watch                   # Watch for changes (daemon mode)
meld workspace validate      # Validate workspace integrity

Context

meld context generate              # Generate context for all files
meld context generate ./src        # Generate for specific path
meld context get <node-id>         # Retrieve context for a node
meld context regenerate            # Force regenerate (--force --no-recursive)

Agents

Agents are LLM-powered workers that generate context frames.

meld agent list              # List configured agents
meld agent create            # Create a new agent interactively
meld agent show <id>         # Show agent details
meld agent validate <id>     # Validate agent configuration

Providers

Providers are LLM backends (OpenAI, Anthropic, Ollama, etc.).

meld provider list           # List configured providers
meld provider create         # Create a new provider interactively
meld provider test <name>    # Test provider connectivity

Configuration

Meld uses XDG directories:

Logging

Logging is on by default and writes to a file under the platform state directory (e.g. $XDG_STATE_HOME/meld/.../meld.log on Linux). Use --quiet to disable logging, or --log-file <path> / MERKLE_LOG_FILE to set the log file path. Configure level, format, and output in [logging] in your config file.

Workspace config

Create .meld/config.toml in your project root:

[storage]
store_path = ".meld/store"
frames_path = ".meld/frames"

[logging]
enabled = true
level = "info"
format = "text"
output = "file"

How It Works

Merkle Tree

Meld builds a Merkle tree of your filesystem. Each file and directory gets a deterministic NodeID based on its content and path. When files change, only affected hashes update — enabling instant change detection.

Context Frames

Context frames are immutable blobs of AI-generated information attached to nodes. Each frame has:

• FrameID — Content-addressed hash
• Basis — The NodeID it describes
• Content — The actual context (summaries, analysis, etc.)

Frames are append-only. New context creates new frames; history is preserved.

Agents & Providers

• Agent — Defines the prompt and role (Reader or Writer)
• Provider — The LLM backend that executes the prompt

Writer agents generate context frames. Reader agents can query context but not write.

Architecture

Filesystem
    ↓
Merkle Tree (deterministic hashing)
    ↓
NodeRecord Store (fast lookups)
    ↓
Context Frames (AI-generated, append-only)
    ↓
Frame Heads (latest frame per node)
    ↓
Context Views (bounded retrieval)

Development

# Run tests
cargo test

# Build release
cargo build --release

# Run with verbose logging
meld --verbose scan

License

MIT OR Apache-2.0