Skip to content

Latest commit

 

History

History
119 lines (94 loc) · 3.42 KB

CLAUDE.md

File metadata and controls

119 lines (94 loc) · 3.42 KB

CLAUDE.md

This file provides guidance to Claude Code and other AI assistants working with this repository.

Project Overview

Memvid is a Rust library that provides a single-file memory layer for AI agents. It packages documents, embeddings, search indices, and metadata into a portable .mv2 file.

Architecture

Core Components

src/
├── lib.rs              # Public API exports
├── memvid/             # Main Memvid struct and operations
│   ├── mod.rs          # Memvid implementation
│   ├── mutation.rs     # Write operations (put, commit, delete)
│   ├── search/         # Search implementations
│   └── ask.rs          # RAG query handling
├── io/                 # File I/O layer
│   ├── header.rs       # File header (4KB)
│   ├── wal.rs          # Write-ahead log
│   └── time_index.rs   # Chronological index
├── lex.rs              # Full-text search (Tantivy)
├── vec.rs              # Vector search (HNSW)
├── clip.rs             # CLIP embeddings
├── whisper.rs          # Audio transcription
└── types/              # Type definitions

File Format (.mv2)

┌────────────────────────────┐
│ Header (4KB)               │
├────────────────────────────┤
│ Embedded WAL (1-64MB)      │
├────────────────────────────┤
│ Data Segments              │
├────────────────────────────┤
│ Lex Index (Tantivy)        │
├────────────────────────────┤
│ Vec Index (HNSW)           │
├────────────────────────────┤
│ Time Index                 │
├────────────────────────────┤
│ TOC (Footer)               │
└────────────────────────────┘

Development Commands

# Build
cargo build
cargo build --release

# Test
cargo test
cargo test --test lifecycle
cargo test -- --nocapture

# Lint
cargo clippy
cargo fmt

# Run examples
cargo run --example basic_usage
cargo run --example pdf_ingestion

# Benchmarks
cargo bench

Key APIs

// Create/Open
let mut mem = Memvid::create("file.mv2")?;
let mut mem = Memvid::open("file.mv2")?;

// Write
mem.put_bytes(content)?;
mem.put_bytes_with_options(content, options)?;
mem.commit()?;

// Search
mem.search(SearchRequest { query, top_k, .. })?;
mem.timeline(TimelineQuery::default())?;

// Verify
Memvid::verify("file.mv2", deep)?;

Feature Flags

Feature Purpose
lex Full-text search (default)
vec Vector similarity search
clip CLIP image embeddings
whisper Audio transcription
encryption AES-256-GCM encryption

Code Style

  • Follow Rust idioms and best practices
  • Use thiserror for error types
  • Use tracing for logging
  • Add doc comments for public APIs
  • Write tests for new functionality

Important Notes

  • Single-file design: Never create sidecar files
  • Crash safety: All writes go through WAL
  • Append-only: Frames are immutable once committed
  • No async: Library is synchronous for simplicity