{"id":36964509,"url":"https://github.com/omar16100/parsnip","last_synced_at":"2026-01-13T19:37:11.744Z","repository":{"id":328583540,"uuid":"1116053925","full_name":"omar16100/parsnip","owner":"omar16100","description":"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.","archived":false,"fork":false,"pushed_at":"2025-12-14T13:32:09.000Z","size":253,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-16T07:26:58.517Z","etag":null,"topics":["ai-memory","cli","graph-database","knowledge-graph","local-first","mcp","redb","rust","tantivy"],"latest_commit_sha":null,"homepage":"https://omar16100.github.io/parsnip/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/omar16100.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-14T05:11:15.000Z","updated_at":"2025-12-14T13:32:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/omar16100/parsnip","commit_stats":null,"previous_names":["omar16100/parsnip"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/omar16100/parsnip","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar16100%2Fparsnip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar16100%2Fparsnip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar16100%2Fparsnip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar16100%2Fparsnip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omar16100","download_url":"https://codeload.github.com/omar16100/parsnip/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omar16100%2Fparsnip/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28397826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","cli","graph-database","knowledge-graph","local-first","mcp","redb","rust","tantivy"],"created_at":"2026-01-13T19:37:11.032Z","updated_at":"2026-01-13T19:37:11.736Z","avatar_url":"https://github.com/omar16100.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# parsnip\n\n**A local-first memory graph for AI assistants and knowledge workers.**\n\n[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)\n[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org/)\n\n[Website](https://omar16100.github.io/parsnip/) · [Documentation](#cli-reference) · [Issues](https://github.com/omar16100/parsnip/issues)\n\n---\n\n## What is parsnip?\n\nParsnip 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.\n\n**The problem:** Memory is scattered across chat logs, notes, and one-off files. AI assistants forget everything between sessions.\n\n**The solution:** A unified, local-first knowledge graph that captures facts once and retrieves them instantly—even with typos, across projects, and offline.\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        PROJECT                              │\n│  ┌─────────────┐                      ┌─────────────┐       │\n│  │   Entity    │      works_at        │   Entity    │       │\n│  │ John_Smith  │ ──────────────────▶  │  Acme_Corp  │       │\n│  │ type:person │                      │type:company │       │\n│  └─────────────┘                      └─────────────┘       │\n│        │                                                    │\n│        │ observations:                                      │\n│        │  - \"Works on distributed systems\"                  │\n│        │  - \"Based in earth\".                               │\n│        │ tags: [engineer, senior]                           │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Features\n\n- **Local-First** — Completely offline. Your data never leaves your machine. Private by design, portable by nature.\n- **Graph-Native** — Store knowledge as entities, relations, and observations. True graph semantics, not SQL with JSON blobs.\n- **5 Search Modes** — Exact, fuzzy (typo-tolerant), full-text (BM25), hybrid (combined), and vector (semantic).\n- **Cross-Project Search** — Query across all projects without mixing namespaces.\n- **MCP Integration** — 12 tools for AI assistants via Model Context Protocol. Works with Claude Desktop.\n- **Graph Traversal** — BFS, Dijkstra shortest path, filtered traversal by entity/relation types.\n- **Multiple Backends** — ReDB (default), SQLite, or in-memory storage.\n- **Fast** — \u003c10ms cold start, \u003c5ms search on 10k entities, \u003c15MB binary.\n\n## Installation\n\n### From Cargo (Recommended)\n\n```bash\ncargo install parsnip\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/omar16100/parsnip.git\ncd parsnip\ncargo build --release\n```\n\n### Feature Flags\n\n```bash\n# Default (ReDB storage)\ncargo install parsnip\n\n# With SQLite backend\ncargo install parsnip --features sqlite\n\n# With SSE/HTTP transport for MCP\ncargo install parsnip --features sse\n\n# With vector/semantic search\ncargo install parsnip --features vector\n```\n\n## Quick Start\n\n```bash\n# Create a project\nparsnip project create work -d \"Work knowledge\"\n\n# Add entities\nparsnip -p work entity add John_Smith -t person -o \"Senior engineer at Acme\" --tag engineer\nparsnip -p work entity add Acme_Corp -t company -o \"Tech company in Singapore\"\n\n# Create a relation\nparsnip -p work relation add John_Smith Acme_Corp -t works_at\n\n# Search\nparsnip -p work search John\nparsnip -p work search \"engineer\" --mode fuzzy\nparsnip -p work search \"distributed systems\" --mode fulltext\n\n# Traverse the graph\nparsnip -p work relation traverse John_Smith -d 2\n\n# Export for backup\nparsnip -p work export -o backup.json\n```\n\n## CLI Reference\n\n### Global Options\n\n| Option | Description |\n|--------|-------------|\n| `-p, --project \u003cNAME\u003e` | Project namespace (default: \"default\") |\n| `-d, --data-dir \u003cPATH\u003e` | Custom data directory |\n| `-f, --format \u003cFMT\u003e` | Output format: table, json, csv |\n| `-v, --verbose` | Increase verbosity (-v, -vv, -vvv) |\n| `-q, --quiet` | Suppress non-error output |\n\n### Entity Commands\n\n```bash\n# Create entity with observations and tags\nparsnip entity add \u003cNAME\u003e -t \u003cTYPE\u003e -o \"observation\" --tag tag1 --tag tag2\n\n# List entities with filters\nparsnip entity list [--type \u003cTYPE\u003e] [--tag \u003cTAG\u003e] [--limit \u003cN\u003e]\n\n# Get entity details\nparsnip entity get \u003cNAME\u003e\n\n# Add observation to existing entity\nparsnip entity observe \u003cNAME\u003e -o \"new fact\"\n\n# Delete entity\nparsnip entity delete \u003cNAME\u003e [--force]\n```\n\n### Relation Commands\n\n```bash\n# Create relation\nparsnip relation add \u003cFROM\u003e \u003cTO\u003e -t \u003cTYPE\u003e [-w \u003cWEIGHT\u003e]\n\n# List relations\nparsnip relation list [--from \u003cNAME\u003e] [--to \u003cNAME\u003e] [--type \u003cTYPE\u003e]\n\n# Delete relation\nparsnip relation delete \u003cFROM\u003e \u003cTO\u003e -t \u003cTYPE\u003e\n\n# Traverse graph (BFS/DFS)\nparsnip relation traverse \u003cSTART\u003e [-d \u003cDEPTH\u003e] [--direction outgoing|incoming|both]\nparsnip relation traverse \u003cSTART\u003e --entity-types person --relation-types works_at\n\n# Find shortest path\nparsnip relation find-path \u003cFROM\u003e \u003cTO\u003e [--weighted] [--relation-types \u003cTYPES\u003e]\n```\n\n### Search Commands\n\n```bash\n# Basic search\nparsnip search \u003cQUERY\u003e\n\n# Search modes\nparsnip search \u003cQUERY\u003e --mode exact      # Substring match\nparsnip search \u003cQUERY\u003e --mode fuzzy      # Typo-tolerant\nparsnip search \u003cQUERY\u003e --mode fulltext   # BM25 ranking\nparsnip search \u003cQUERY\u003e --mode hybrid     # Fuzzy + fulltext\n\n# Filter by tags\nparsnip search --tag engineer --tag senior\n\n# Cross-project search\nparsnip search \u003cQUERY\u003e --all-projects\n\n# With pagination\nparsnip search \u003cQUERY\u003e --limit 20 --page 1\n```\n\n### Project Commands\n\n```bash\n# List all projects\nparsnip project list\n\n# Create project\nparsnip project create \u003cNAME\u003e [-d \"description\"]\n\n# Set default project\nparsnip project use \u003cNAME\u003e\n\n# Get project stats\nparsnip project stats\n\n# Delete project\nparsnip project delete \u003cNAME\u003e [--force]\n```\n\n### Import/Export Commands\n\n```bash\n# Export single project\nparsnip export -o backup.json\n\n# Export all projects\nparsnip export --all-projects -o full-backup.json\n\n# Import to current project\nparsnip import data.json\n\n# Import to specific project\nparsnip import data.json --target-project newproject\n\n# Merge with existing data\nparsnip import data.json --merge\n```\n\n### Server Commands\n\n```bash\n# Start MCP server (stdio)\nparsnip serve\n\n# Start MCP server (HTTP/SSE) - requires --features sse\nparsnip serve -t sse --port 3000 --host 0.0.0.0\n```\n\n## MCP Integration\n\nParsnip includes a Model Context Protocol (MCP) server that gives AI assistants persistent memory.\n\n### Claude Desktop Setup\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"parsnip\": {\n      \"command\": \"parsnip\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n### Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `search_knowledge` | Search entities with fuzzy/fulltext/hybrid modes |\n| `create_entities` | Batch create entities with observations and tags |\n| `add_observations` | Add facts to existing entities |\n| `create_relations` | Create typed relations between entities |\n| `delete_entities` | Remove entities (cascades relations) |\n| `delete_observations` | Remove specific observations |\n| `delete_relations` | Remove relations |\n| `read_graph` | Get complete project graph |\n| `open_nodes` | Retrieve specific entities by name |\n| `add_tags` | Add tags to entities |\n| `remove_tags` | Remove tags from entities |\n| `traverse_graph` | BFS/Dijkstra traversal with filters |\n\n## Search Modes\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| **Exact** | Substring matching | Precise queries, known names |\n| **Fuzzy** | Nucleo-based, typo-tolerant | Misspellings, partial recall |\n| **Full-text** | Tantivy BM25 ranking | Natural language queries |\n| **Hybrid** | Fuzzy + full-text combined | Best overall recall |\n| **Vector** | Cosine similarity (embeddings) | Semantic search |\n\n### Fuzzy Search Configuration\n\n```bash\n# Adjust threshold (0.0 = match everything, 1.0 = exact only)\nparsnip search \"john smth\" --mode fuzzy --threshold 0.3\n```\n\n## Storage Backends\n\n### ReDB (Default)\n\nEmbedded key-value store with ACID transactions. Zero external dependencies.\n\n```bash\n# Data stored at:\n# macOS: ~/Library/Application Support/parsnip/parsnip.redb\n# Linux: ~/.local/share/parsnip/parsnip.redb\n```\n\n### SQLite\n\nRelational backend compatible with SQL tools.\n\n```bash\ncargo install parsnip --features sqlite\n```\n\n### Memory\n\nIn-memory storage for testing. No persistence.\n\n```bash\n# Used automatically in tests\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PARSNIP_DATA_DIR` | Data directory path | Platform-specific |\n| `PARSNIP_PROJECT` | Default project name | \"default\" |\n| `PARSNIP_LOG` | Log level (trace/debug/info/warn/error) | \"info\" |\n\n### Data Directory Locations\n\n| Platform | Path |\n|----------|------|\n| macOS | `~/Library/Application Support/parsnip/` |\n| Linux | `~/.local/share/parsnip/` |\n| Windows | `%APPDATA%\\parsnip\\` |\n\n## Performance\n\n| Operation | Target |\n|-----------|--------|\n| Cold start | \u003c10ms |\n| Entity create | \u003c1ms |\n| Batch create (100) | \u003c10ms |\n| Exact search (10k entities) | \u003c5ms |\n| Fuzzy search (10k entities) | \u003c20ms |\n| Full-text search (10k entities) | \u003c10ms |\n| Cross-project search (100k) | \u003c100ms |\n| Graph traversal (depth 3) | \u003c50ms |\n| Binary size (stripped) | \u003c15MB |\n| Idle memory | \u003c20MB |\n\n## Architecture\n\n```\nparsnip/\n├── crates/\n│   ├── parsnip-core/       # Core types: Entity, Relation, Observation, Project\n│   ├── parsnip-storage/    # Storage backends: ReDB, SQLite, Memory\n│   ├── parsnip-search/     # Search engines: Exact, Fuzzy, FullText, Hybrid, Vector\n│   ├── parsnip-cli/        # CLI binary with all commands\n│   └── parsnip-mcp/        # MCP server with 12 tools\n├── docs/\n│   ├── spec.md             # Full specification\n│   └── index.html          # Website\n└── tests/                  # Integration tests\n```\n\n### Crate Dependencies\n\n```\nparsnip-cli\n    ├── parsnip-core\n    ├── parsnip-storage\n    │   └── parsnip-core\n    ├── parsnip-search\n    │   └── parsnip-core\n    └── parsnip-mcp\n        ├── parsnip-core\n        ├── parsnip-storage\n        └── parsnip-search\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`cargo test`)\n5. Submit a pull request\n\n### Development Setup\n\n```bash\ngit clone https://github.com/omar16100/parsnip.git\ncd parsnip\ncargo build\ncargo test\n```\n\n### Code Style\n\n- Format with `cargo fmt`\n- Lint with `cargo clippy`\n- Test coverage target: \u003e80%\n\n## License\n\nDual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your option.\n\n---\n\n**Built with Rust** · [Website](https://omar16100.github.io/parsnip/) · [GitHub](https://github.com/omar16100/parsnip)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomar16100%2Fparsnip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomar16100%2Fparsnip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomar16100%2Fparsnip/lists"}