Get started with vipune in 5 minutes.
# Install from source
cargo install --git https://github.com/randomm/vipune vipune
# Or build from source
git clone https://github.com/randomm/vipune.git
cd vipune
cargo build --release
cargo install --path .First run: vipune will automatically download the ONNX model (~400MB) to ~/.vipune/models/. This happens once and takes 30-60 seconds depending on your connection.
# Store a simple memory
vipune add "Alice works at Microsoft as a senior engineer"
# Output: Added memory: 123e4567-e89b-12d3-a456-426614174000vipune stores:
- The text content
- Semantic embedding (384 dimensions)
- Creation timestamp
- Project ID (auto-detected from git)
# Search by meaning, not keywords
vipune search "where does alice work"
# Output:
# 123e4567-e89b-12d3-a456-426614174000 [score: 0.95]
# Alice works at Microsoft as a senior engineerTips for searching:
- Use natural language: "how do we handle payments", "database schema for users"
- Try variations if results aren't ideal: same meaning, different words
- Check similarity scores: 0.9+ = very similar, 0.7-0.9 = related, below 0.7 = distant
Recency scoring: Search results can be biased toward recent memories:
# Default balance (70% semantic, 30% recency)
vipune search "authentication"
# High recency bias (recent memories rank higher)
vipune search "authentication" --recency 0.7
# Pure semantic search (no time bias)
vipune search "authentication" --recency 0.0vipune warns when you add duplicate or very similar memories.
# Try adding a similar memory
vipune add "Alice is a senior engineer at Microsoft"
# Output:
# Conflicts detected: 1 similar memory/memories found
# Proposed: Alice is a senior engineer at Microsoft
# Use --force to add anyway
# 123e4567-e89b-12d3-a456-426614174000 (similarity: 0.94)
# Alice works at Microsoft as a senior engineer
# Exit code: 2
# Options when conflicts occur:
# 1. Skip (don't add)
# 2. Force add to bypass conflict detection
vipune add "Alice is a senior engineer at Microsoft" --force
# 3. Update existing memory instead
vipune update 123e4567-e89b-12d3-a456-426614174000 "Alice works at Microsoft as a senior engineer (since 2020)"Why conflict detection matters:
- Prevents redundant memories
- Maintains knowledge quality
- Forces agents to resolve ambiguity explicitly
vipune works with zero configuration. Customize only if needed.
# See where memories are stored (default: ~/.vipune/memories.db)
ls ~/.vipune/memories.db# Use custom database location
vipune add "Test" --db-path /tmp/test.db
# Or set environment variable
export VIPUNE_DATABASE_PATH="/custom/path/memories.db"
vipune add "Test"
# Override project scope via environment
export VIPUNE_PROJECT="my-custom-project"
vipune add "Project-specific memory"Default: 0.85 (memories with similarity ≥ 0.85 trigger conflicts)
# More strict (catch near-duplicates)
export VIPUNE_SIMILARITY_THRESHOLD="0.9"
# More permissive (only exact/near-exact matches conflict)
export VIPUNE_SIMILARITY_THRESHOLD="0.95"
# Disable conflict detection (not recommended)
export VIPUNE_SIMILARITY_THRESHOLD="1.0"Default: 0.3 (30% recency, 70% semantic similarity)
# High recency bias (recent memories always rank higher)
export VIPUNE_RECENCY_WEIGHT="0.8"
# Pure semantic search (no time bias)
export VIPUNE_RECENCY_WEIGHT="0.0"
# Balance semantic and recency equally
export VIPUNE_RECENCY_WEIGHT="0.5"Create ~/.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# After reading code or documentation
vipune add "Authentication middleware validates JWT tokens in src/auth/middleware.rs"
# Tag with metadata for organization
vipune add "Users table schema: id, email, password_hash, created_at, updated_at" \
--metadata '{"table": "users", "schema": true}'# Search first to avoid duplicates
vipune search "authentication implementation"
# If similar results found, update existing instead of adding new
vipune update <existing-id> "Auth uses JWT with refresh tokens (expires in 24h)"# See all memories for current project
vipune list
# More results
vipune list --limit 50
# Export to JSON for processing
vipune list --limit 9999 --json > memories.json# Memories are scoped to git repository
cd ~/projects/myapp
vipune add "Myapp uses PostgreSQL"
cd ~/projects/otherproject
vipune add "Otherapp uses SQLite"
# Search respects project scope automatically
vipune search "database" # Only finds memories for otherproject# Add memory and get ID
ID=$(vipune add --json "Fact" | jq -r '.id')
# Search and extract highest similarity
vipune search --json "test" | jq '.results[0]'
# Check for conflicts in script
if vipune add --json "New fact" | jq -e '.conflicts' > /dev/null; then
echo "Conflict detected!"
fi# Find recent changes first (high recency bias)
vipune search "API changes" --recency 0.8
# Find fundamental knowledge (pure semantic)
vipune search "authentication patterns" --recency 0.0
# Balance relevance and freshness
vipune search "database schema" --recency 0.4If the first run fails to download the model:
# Clear cache and retry
rm -rf ~/.vipune/models/
vipune add "Test" # Will re-downloadIf legitimate memories are flagged as conflicts:
# Lower threshold temporarily
export VIPUNE_SIMILARITY_THRESHOLD="0.9"
vipune add "Your memory"
# Or force add the memory
vipune add "Your memory" --force# Check project scope (--project is a global flag, must come before command)
vipune --project "git@github.com:user/repo.git" list
# Or search without project filter (if using default scope)
vipune --project "default" search "query"If you want recent memories to rank higher:
# Increase recency bias
export VIPUNE_RECENCY_WEIGHT="0.7"
vipune search "recent changes"
# Or use --recency flag per search
vipune search "recent changes" --recency 0.7# Only one vipune process can access the database at a time
# Close other terminals running vipune, then retry- Read the complete CLI reference
- Explore agent integration patterns in the README
- Check project issues for upcoming features