vipune /ˈʋi.pu.ne/

              ███                                          
             ░░░                                           
 █████ █████ ████  ████████  █████ ████ ████████    ██████ 
░░███ ░░███ ░░███ ░░███░░███░░███ ░███ ░░███░░███  ███░░███
 ░███  ░███  ░███  ░███ ░███ ░███ ░███  ░███ ░███ ░███████ 
 ░░███ ███   ░███  ░███ ░███ ░███ ░███  ░███ ░███ ░███░░░  
  ░░█████    █████ ░███████  ░░████████ ████ █████░░██████ 
   ░░░░░    ░░░░░  ░███░░░    ░░░░░░░░ ░░░░ ░░░░░  ░░░░░░  
                   ░███                                    
                   █████                                   
                  ░░░░░                                    

A minimal memory layer for AI agents.

In Finnish mythology, Antero Vipunen is a giant who sleeps underground, holding all the world's knowledge and ancient songs. vipune is your agent's sleeping giant — a local knowledge store that remembers everything.

Store semantic memories, search by meaning, and detect conflicts. Single binary CLI. No API keys required.

Features

• Semantic search - Find memories by meaning, not keywords (ONNX embeddings, bge-small-en-v1.5)
• Conflict detection - Automatically warns when adding duplicate or similar memories
• Zero configuration - Works out of the box (auto-detected git projects, sensible defaults)
• Single binary - Just one CLI tool, no daemon, no database server
• No API keys - Everything runs locally, no network dependencies
• Project scoped - Memories isolated by git repository

Installation

Platform Support

Supported: macOS ARM64, Linux x86_64, Linux ARM64
Not supported: Windows (due to ONNX Runtime compilation complexity)

Prerequisites

For source installation:

• Rust 1.70+ (install via https://rustup.rs)
• System dependencies for ONNX Runtime:
  • Linux: libgomp1, libc6
  • macOS: None required

Pre-built binary

macOS Apple Silicon (arm64)

# Download
curl -sSfLO https://github.com/randomm/vipune/releases/latest/download/vipune-aarch64-apple-darwin.tar.xz

# Extract
tar xf vipune-aarch64-apple-darwin.tar.xz

# Install to system directory (requires sudo)
sudo mv vipune /usr/local/bin/

# Or install to user directory (no sudo)
mkdir -p ~/.local/bin
mv vipune ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

Linux x86_64

curl -sSfLO https://github.com/randomm/vipune/releases/latest/download/vipune-x86_64-unknown-linux-gnu.tar.xz
tar xf vipune-x86_64-unknown-linux-gnu.tar.xz
sudo mv vipune /usr/local/bin/

Linux ARM64

curl -sSfLO https://github.com/randomm/vipune/releases/latest/download/vipune-aarch64-unknown-linux-gnu.tar.xz
tar xf vipune-aarch64-unknown-linux-gnu.tar.xz
sudo mv vipune /usr/local/bin/

Build from source

Latest release (recommended)

cargo install vipune

Or clone and build manually

git clone https://github.com/randomm/vipune.git
cd vipune && cargo build --release

# Binary at ./target/release/vipune

# Add to PATH temporarily
export PATH="$(pwd)/target/release:$PATH"

# Or install permanently
sudo cp target/release/vipune /usr/local/bin/

Uninstall

# Remove pre-built binary
sudo rm /usr/local/bin/vipune

# Remove from user directory
rm ~/.local/bin/vipune

# Remove via cargo
cargo uninstall vipune

# Clear data (optional)
rm -rf ~/.vipune ~/.config/vipune

Quick Start

# Add a memory
vipune add "Alice works at Microsoft"

# Search by semantic meaning
vipune search "where does alice work"

# Add with metadata (optional)
vipune add "Auth uses JWT tokens" --metadata '{"topic": "authentication"}'

CLI Commands

Complete CLI reference • Quickstart guide

Library Usage

vipune can also be used as a Rust crate for programmatic integration:

# Cargo.toml
[dependencies]
vipune = "0.1"

use vipune::{Config, MemoryStore, detect_project};

// Initialize memory store
let config = Config::default();
let mut store = MemoryStore::new(
    config.database_path.as_path(),
    &config.embedding_model,
    config.clone()
).expect("Failed to initialize store");

// Add a memory
let project_id = "my-project";
let memory_id = store.add(&project_id, "Alice works at Microsoft", None)
    .expect("Failed to add memory");

// Search memories
let results = store.search(&project_id, "where does alice work", 10, 0.0)
    .expect("Failed to search");

for memory in results {
    println!("{:.2}: {}", memory.similarity.unwrap_or(0.0), memory.content);
}

See the crate documentation at docs.rs for complete API reference.

Configuration

vipune works with zero configuration. All paths use the user's home directory:

Default paths:

• Database: ~/.vipune/memories.db
• Model cache: ~/.vipune/models/
• Config file: ~/.config/vipune/config.toml

Environment variables (override defaults):

• VIPUNE_DATABASE_PATH - SQLite database location
• VIPUNE_EMBEDDING_MODEL - HuggingFace model ID (default: BAAI/bge-small-en-v1.5)
• VIPUNE_MODEL_CACHE - Model download cache directory
• VIPUNE_PROJECT - Project identifier (overrides auto-detection)
• VIPUNE_SIMILARITY_THRESHOLD - Conflict detection threshold, 0.0-1.0 (default: 0.85)
• VIPUNE_RECENCY_WEIGHT - Recency bias in search results, 0.0-1.0 (default: 0.3)

Config file (~/.config/vipune/config.toml):

database_path = "~/.vipune/memories.db"
embedding_model = "BAAI/bge-small-en-v1.5"
model_cache = "~/.vipune/models"
similarity_threshold = 0.85
recency_weight = 0.3

Agent Integration

vipune works with any agent that can run shell commands — no plugins, adapters, or API keys required. Configure your agent with a few lines of instructions, grant shell command permissions, and the agent can use vipune search and vipune add to maintain persistent memory across tasks.

→ See Agent Integration Guide for per-tool setup instructions (Claude Code, Cursor, Windsurf, Cline, Roo Code, GitHub Copilot, Goose, Aider, OpenCode, Zed, and more).

Exit codes for agent workflows:

• 0 - Success
• 1 - Error (missing file, invalid input, etc.)
• 2 - Conflicts detected (similar memories found)

Recency Scoring

Search results can be weighted by recency using the --recency flag or VIPUNE_RECENCY_WEIGHT config:

# Increase recency bias (recent memories rank higher)
vipune search "authentication" --recency 0.7

# Pure semantic similarity (no recency bias)
vipune search "authentication" --recency 0.0

The final score combines semantic similarity and recency time decay:

• score = (1 - recency_weight) * similarity + recency_weight * time_score
• Default balance: 70% semantic, 30% recency

License

Apache-2.0 © Janni Turunen

Links

• GitHub
• Issues
• CLI Reference
• Quickstart