Skip to content
/ parsnip Public

A local-first memory graph for AI assistants. Single-binary graph database with entities, relations, and observations. 5 search modes, MCP integration, cross-project queries. Private, fast, portable.

omar16100.github.io/parsnip/

License

Unknown, MIT licenses found

Licenses found

Unknown
LICENSE-APACHE
MIT
LICENSE-MIT
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

omar16100/parsnip

BranchesTags

Repository files navigation

parsnip

A local-first memory graph for AI assistants and knowledge workers.

License Rust

Website · Documentation · Issues

What is parsnip?

Parsnip is a single-binary graph database designed to store durable facts as entities and relations, enabling fast, reliable retrieval through integrated search and graph traversal.

The problem: Memory is scattered across chat logs, notes, and one-off files. AI assistants forget everything between sessions.

The solution: A unified, local-first knowledge graph that captures facts once and retrieves them instantly—even with typos, across projects, and offline.

┌─────────────────────────────────────────────────────────────┐
│                        PROJECT                              │
│  ┌─────────────┐                      ┌─────────────┐       │
│  │   Entity    │      works_at        │   Entity    │       │
│  │ John_Smith  │ ──────────────────▶  │  Acme_Corp  │       │
│  │ type:person │                      │type:company │       │
│  └─────────────┘                      └─────────────┘       │
│        │                                                    │
│        │ observations:                                      │
│        │  - "Works on distributed systems"                  │
│        │  - "Based in earth".                               │
│        │ tags: [engineer, senior]                           │
└─────────────────────────────────────────────────────────────┘

Features

  • Local-First — Completely offline. Your data never leaves your machine. Private by design, portable by nature.
  • Graph-Native — Store knowledge as entities, relations, and observations. True graph semantics, not SQL with JSON blobs.
  • 5 Search Modes — Exact, fuzzy (typo-tolerant), full-text (BM25), hybrid (combined), and vector (semantic).
  • Cross-Project Search — Query across all projects without mixing namespaces.
  • MCP Integration — 12 tools for AI assistants via Model Context Protocol. Works with Claude Desktop.
  • Graph Traversal — BFS, Dijkstra shortest path, filtered traversal by entity/relation types.
  • Multiple Backends — ReDB (default), SQLite, or in-memory storage.
  • Fast — <10ms cold start, <5ms search on 10k entities, <15MB binary.

Installation

From Cargo (Recommended)

cargo install parsnip

From Source

git clone https://github.com/omar16100/parsnip.git
cd parsnip
cargo build --release

Feature Flags

# Default (ReDB storage)
cargo install parsnip

# With SQLite backend
cargo install parsnip --features sqlite

# With SSE/HTTP transport for MCP
cargo install parsnip --features sse

# With vector/semantic search
cargo install parsnip --features vector

Quick Start

# Create a project
parsnip project create work -d "Work knowledge"

# Add entities
parsnip -p work entity add John_Smith -t person -o "Senior engineer at Acme" --tag engineer
parsnip -p work entity add Acme_Corp -t company -o "Tech company in Singapore"

# Create a relation
parsnip -p work relation add John_Smith Acme_Corp -t works_at

# Search
parsnip -p work search John
parsnip -p work search "engineer" --mode fuzzy
parsnip -p work search "distributed systems" --mode fulltext

# Traverse the graph
parsnip -p work relation traverse John_Smith -d 2

# Export for backup
parsnip -p work export -o backup.json

CLI Reference

Global Options

Option Description
-p, --project <NAME> Project namespace (default: "default")
-d, --data-dir <PATH> Custom data directory
-f, --format <FMT> Output format: table, json, csv
-v, --verbose Increase verbosity (-v, -vv, -vvv)
-q, --quiet Suppress non-error output

Entity Commands

# Create entity with observations and tags
parsnip entity add <NAME> -t <TYPE> -o "observation" --tag tag1 --tag tag2

# List entities with filters
parsnip entity list [--type <TYPE>] [--tag <TAG>] [--limit <N>]

# Get entity details
parsnip entity get <NAME>

# Add observation to existing entity
parsnip entity observe <NAME> -o "new fact"

# Delete entity
parsnip entity delete <NAME> [--force]

Relation Commands

# Create relation
parsnip relation add <FROM> <TO> -t <TYPE> [-w <WEIGHT>]

# List relations
parsnip relation list [--from <NAME>] [--to <NAME>] [--type <TYPE>]

# Delete relation
parsnip relation delete <FROM> <TO> -t <TYPE>

# Traverse graph (BFS/DFS)
parsnip relation traverse <START> [-d <DEPTH>] [--direction outgoing|incoming|both]
parsnip relation traverse <START> --entity-types person --relation-types works_at

# Find shortest path
parsnip relation find-path <FROM> <TO> [--weighted] [--relation-types <TYPES>]

Search Commands

# Basic search
parsnip search <QUERY>

# Search modes
parsnip search <QUERY> --mode exact      # Substring match
parsnip search <QUERY> --mode fuzzy      # Typo-tolerant
parsnip search <QUERY> --mode fulltext   # BM25 ranking
parsnip search <QUERY> --mode hybrid     # Fuzzy + fulltext

# Filter by tags
parsnip search --tag engineer --tag senior

# Cross-project search
parsnip search <QUERY> --all-projects

# With pagination
parsnip search <QUERY> --limit 20 --page 1

Project Commands

# List all projects
parsnip project list

# Create project
parsnip project create <NAME> [-d "description"]

# Set default project
parsnip project use <NAME>

# Get project stats
parsnip project stats

# Delete project
parsnip project delete <NAME> [--force]

Import/Export Commands

# Export single project
parsnip export -o backup.json

# Export all projects
parsnip export --all-projects -o full-backup.json

# Import to current project
parsnip import data.json

# Import to specific project
parsnip import data.json --target-project newproject

# Merge with existing data
parsnip import data.json --merge

Server Commands

# Start MCP server (stdio)
parsnip serve

# Start MCP server (HTTP/SSE) - requires --features sse
parsnip serve -t sse --port 3000 --host 0.0.0.0

MCP Integration

Parsnip includes a Model Context Protocol (MCP) server that gives AI assistants persistent memory.

Claude Desktop Setup

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "parsnip": {
      "command": "parsnip",
      "args": ["mcp"]
    }
  }
}

Available MCP Tools

Tool Description
search_knowledge Search entities with fuzzy/fulltext/hybrid modes
create_entities Batch create entities with observations and tags
add_observations Add facts to existing entities
create_relations Create typed relations between entities
delete_entities Remove entities (cascades relations)
delete_observations Remove specific observations
delete_relations Remove relations
read_graph Get complete project graph
open_nodes Retrieve specific entities by name
add_tags Add tags to entities
remove_tags Remove tags from entities
traverse_graph BFS/Dijkstra traversal with filters

Search Modes

Mode Description Use Case
Exact Substring matching Precise queries, known names
Fuzzy Nucleo-based, typo-tolerant Misspellings, partial recall
Full-text Tantivy BM25 ranking Natural language queries
Hybrid Fuzzy + full-text combined Best overall recall
Vector Cosine similarity (embeddings) Semantic search

Fuzzy Search Configuration

# Adjust threshold (0.0 = match everything, 1.0 = exact only)
parsnip search "john smth" --mode fuzzy --threshold 0.3

Storage Backends

ReDB (Default)

Embedded key-value store with ACID transactions. Zero external dependencies.

# Data stored at:
# macOS: ~/Library/Application Support/parsnip/parsnip.redb
# Linux: ~/.local/share/parsnip/parsnip.redb

SQLite

Relational backend compatible with SQL tools.

cargo install parsnip --features sqlite

Memory

In-memory storage for testing. No persistence.

# Used automatically in tests

Configuration

Environment Variables

Variable Description Default
PARSNIP_DATA_DIR Data directory path Platform-specific
PARSNIP_PROJECT Default project name "default"
PARSNIP_LOG Log level (trace/debug/info/warn/error) "info"

Data Directory Locations

Platform Path
macOS ~/Library/Application Support/parsnip/
Linux ~/.local/share/parsnip/
Windows %APPDATA%\parsnip\

Performance

Operation Target
Cold start <10ms
Entity create <1ms
Batch create (100) <10ms
Exact search (10k entities) <5ms
Fuzzy search (10k entities) <20ms
Full-text search (10k entities) <10ms
Cross-project search (100k) <100ms
Graph traversal (depth 3) <50ms
Binary size (stripped) <15MB
Idle memory <20MB

Architecture

parsnip/
├── crates/
│   ├── parsnip-core/       # Core types: Entity, Relation, Observation, Project
│   ├── parsnip-storage/    # Storage backends: ReDB, SQLite, Memory
│   ├── parsnip-search/     # Search engines: Exact, Fuzzy, FullText, Hybrid, Vector
│   ├── parsnip-cli/        # CLI binary with all commands
│   └── parsnip-mcp/        # MCP server with 12 tools
├── docs/
│   ├── spec.md             # Full specification
│   └── index.html          # Website
└── tests/                  # Integration tests

Crate Dependencies

parsnip-cli
    ├── parsnip-core
    ├── parsnip-storage
    │   └── parsnip-core
    ├── parsnip-search
    │   └── parsnip-core
    └── parsnip-mcp
        ├── parsnip-core
        ├── parsnip-storage
        └── parsnip-search

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (cargo test)
  5. Submit a pull request

Development Setup

git clone https://github.com/omar16100/parsnip.git
cd parsnip
cargo build
cargo test

Code Style

  • Format with cargo fmt
  • Lint with cargo clippy
  • Test coverage target: >80%

License

Dual-licensed under MIT or Apache-2.0 at your option.

Built with Rust · Website · GitHub

About

A local-first memory graph for AI assistants. Single-binary graph database with entities, relations, and observations. 5 search modes, MCP integration, cross-project queries. Private, fast, portable.

omar16100.github.io/parsnip/

Topics

rust cli mcp knowledge-graph graph-database tantivy local-first redb ai-memory

Resources

Readme

License

Unknown, MIT licenses found

Licenses found

Unknown
LICENSE-APACHE
MIT
LICENSE-MIT
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.1.0 Latest
Dec 14, 2025

Packages

No packages published

Languages