███
░░░
█████ █████ ████ ████████ █████ ████ ████████ ██████
░░███ ░░███ ░░███ ░░███░░███░░███ ░███ ░░███░░███ ███░░███
░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███████
░░███ ███ ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███░░░
░░█████ █████ ░███████ ░░████████ ████ █████░░██████
░░░░░ ░░░░░ ░███░░░ ░░░░░░░░ ░░░░ ░░░░░ ░░░░░░
░███
█████
░░░░░
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.
- 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
Supported: macOS ARM64, Linux x86_64, Linux ARM64
Not supported: Windows (due to ONNX Runtime compilation complexity)
For source installation:
- Rust 1.70+ (install via https://rustup.rs)
- System dependencies for ONNX Runtime:
- Linux: libgomp1, libc6
- macOS: None required
macOS Apple Silicon (arm64)
Download and extract:
curl -sSfLO https://github.com/randomm/vipune/releases/latest/download/vipune-aarch64-apple-darwin.tar.xz
tar xf vipune-aarch64-apple-darwin.tar.xzInstall to system PATH (requires sudo):
sudo mkdir -p /usr/local/bin && 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"Add the
exportline to your~/.zshrcor~/.bashrcto make it permanent.
Linux x86_64
Download and extract:
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.xzInstall to system PATH:
sudo mkdir -p /usr/local/bin && sudo mv vipune /usr/local/bin/Linux ARM64
Download and extract:
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.xzInstall to system PATH:
sudo mkdir -p /usr/local/bin && sudo mv vipune /usr/local/bin/Latest release (recommended)
cargo install vipuneOr clone and build manually
git clone https://github.com/randomm/vipune.git
cd vipune && cargo build --releaseThe binary will be at ./target/release/vipune. Install it:
sudo mkdir -p /usr/local/bin && sudo cp target/release/vipune /usr/local/bin/Or add to PATH temporarily:
export PATH="$(pwd)/target/release:$PATH"Remove the binary (whichever method you used to install):
sudo rm /usr/local/bin/vipunerm ~/.local/bin/vipunecargo uninstall vipuneOptionally, clear all data:
rm -rf ~/.vipune ~/.config/vipuneAdd 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"}'| Command | Description |
|---|---|
vipune add <text> |
Store a memory |
vipune search <query> |
Find memories by meaning |
vipune get <id> |
Retrieve a memory by ID |
vipune list |
List all memories |
vipune delete <id> |
Delete a memory |
vipune update <id> <text> |
Update a memory's content |
vipune version |
Show version |
Complete CLI reference • Quickstart guide
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.
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 locationVIPUNE_EMBEDDING_MODEL- HuggingFace model ID (default:BAAI/bge-small-en-v1.5)VIPUNE_MODEL_CACHE- Model download cache directoryVIPUNE_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.3vipune 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- Success1- Error (missing file, invalid input, etc.)2- Conflicts detected (similar memories found)
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.0The final score combines semantic similarity and recency time decay:
score = (1 - recency_weight) * similarity + recency_weight * time_score- Default balance: 70% semantic, 30% recency
Apache-2.0 © Janni Turunen