{"id":49863102,"url":"https://github.com/mayonaiselover/heirloom","last_synced_at":"2026-05-19T02:01:22.454Z","repository":{"id":357810626,"uuid":"1236545820","full_name":"MayonaiseLover/heirloom","owner":"MayonaiseLover","description":"Local-first, MCP-native personal memory for AI. Every AI is amnesiac — Heirloom gives them yours.","archived":false,"fork":false,"pushed_at":"2026-05-14T10:29:15.000Z","size":680,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T23:50:15.714Z","etag":null,"topics":["agents","ai","claude-memory","encryption","local-first","mcp","memory","personal-knowledge-management","privacy","rust","sqlite"],"latest_commit_sha":null,"homepage":"https://heirlooom.web.app","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MayonaiseLover.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-12T10:52:03.000Z","updated_at":"2026-05-14T11:07:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MayonaiseLover/heirloom","commit_stats":null,"previous_names":["mayonaiselover/heirloom"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/MayonaiseLover/heirloom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MayonaiseLover%2Fheirloom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MayonaiseLover%2Fheirloom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MayonaiseLover%2Fheirloom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MayonaiseLover%2Fheirloom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MayonaiseLover","download_url":"https://codeload.github.com/MayonaiseLover/heirloom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MayonaiseLover%2Fheirloom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33161411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"ssl_error","status_checked_at":"2026-05-17T22:39:10.741Z","response_time":107,"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":["agents","ai","claude-memory","encryption","local-first","mcp","memory","personal-knowledge-management","privacy","rust","sqlite"],"created_at":"2026-05-14T22:11:59.463Z","updated_at":"2026-05-19T02:01:22.447Z","avatar_url":"https://github.com/MayonaiseLover.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/logo.svg\" width=\"96\" alt=\"Heirloom logo\" /\u003e\n\n# Heirloom\n\n**Every AI is amnesiac. Heirloom gives them yours.**\n\nA local-first, MCP-native personal memory layer for AI. One install, then every MCP-aware AI tool — Claude, Cursor, Antigravity, OpenClaw, ChatGPT, custom agents — suddenly knows you.\n\n[![CI](https://github.com/MayonaiseLover/heirloom/actions/workflows/ci.yml/badge.svg)](https://github.com/MayonaiseLover/heirloom/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed.svg)](https://modelcontextprotocol.io)\n[![Rust](https://img.shields.io/badge/built_with-Rust-orange.svg)](https://www.rust-lang.org/)\n[![Encrypted](https://img.shields.io/badge/encryption-XChaCha20--Poly1305-34d399.svg)](docs/design/sync-protocol.md)\n\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo.svg\" alt=\"Heirloom demo — every AI suddenly knows you\" width=\"880\"/\u003e\n\u003c/p\u003e\n\n---\n\nEvery AI tool you use has its own siloed, half-broken memory. You re-explain yourself every conversation. You switch tools and lose months of context. The closed alternatives ([Rewind](https://rewind.ai), [Microsoft Recall](https://www.microsoft.com/en-us/windows/copilot-plus-pcs)) ship your life to someone else's server. The \"claude-mem\" cluster locks you to Claude Code and usually needs npm, Python, or external services like Chroma or Supabase.\n\nHeirloom is a single Rust binary that ingests what *you* let it (notes, browser history, AI conversations, Slack and Obsidian exports), stores it locally in an encrypted SQLite database, and exposes it over [**MCP**](https://modelcontextprotocol.io) so any AI can ask: *\"what does the user know about this?\"*\n\nYour memory is a file you own. Not a SaaS account.\n\n## Why Heirloom over the alternatives?\n\n| | **Heirloom** | claude-mem | claude-brain | claude-memory | Rewind / Recall |\n|---|---|---|---|---|---|\n| Works with any MCP client (Claude, Cursor, Antigravity, OpenClaw, …) | ✅ | ❌ Claude Code only | ❌ Claude Code only | ❌ Claude Code only | ❌ Single app |\n| Single binary, no runtime | ✅ Rust | ❌ Needs npm + worker | ✅ Rust | ❌ Needs npm | ✅ |\n| No API keys required | ✅ | ❌ LLM for compression | ✅ | ❌ Supabase | ❌ |\n| Local-first by default | ✅ | Partial (Chroma) | ✅ | ❌ Cloud sync | ❌ |\n| At-rest encryption | ✅ XChaCha20-Poly1305 / Argon2id | ❌ | ❌ | ❌ | ✅ |\n| Hybrid lexical + vector search | ✅ BM25 + n-gram TF-IDF | ✅ | Lexical only | ✅ | ✅ |\n| 8 built-in source ingesters | ✅ | ❌ AI sessions only | ❌ | ❌ AI sessions only | ✅ |\n| Web viewer included | ✅ `localhost:7878` | ✅ | ❌ | ❌ | ✅ |\n| Auto-capture daemon | ✅ `heirloom watch` | ✅ hooks | ❌ | ✅ hooks | ✅ |\n| Pluggable ingester architecture | ✅ ~50-line plugins | ❌ | ❌ | ❌ | ❌ |\n| Encrypted multi-device sync | ✅ snapshot push + pull shipped | ❌ | ❌ | ✅ Supabase | ❌ |\n| **Self-hostable team-memory server** | ✅ **`heirloom-team-server`** | ❌ | ❌ | ❌ | ❌ |\n| Open source | ✅ MIT | ✅ Apache | ✅ | ✅ MIT | ❌ |\n\n## Quickstart\n\n```bash\ncurl -sSL https://heirlooom.web.app/install | sh\nheirloom init\n\n# Ingest something\nheirloom ingest fs --path ~/Documents/notes\nheirloom ingest browser            # auto-detects Chrome/Brave/Arc/Edge/Vivaldi\nheirloom ingest firefox            # places.sqlite history\nheirloom ingest claude-code        # ~/.claude/projects/ sessions\n\n# Try it\nheirloom search \"what was that auth bug\"\n\n# Open the dashboard\nheirloom desktop\n```\n\n### Building from source\n\nIf no pre-built release is available for your platform yet, the installer falls back to building from source automatically. You can also do it manually:\n\n```bash\n# Requires Rust 1.83+ (https://rustup.rs)\ngit clone https://github.com/MayonaiseLover/heirloom\ncd heirloom\ncargo install --path crates/heirloom-cli      # installs the `heirloom` binary\ncargo install --path crates/heirloom-team     # installs `heirloom-team-server` (optional)\n```\n\nThe first build takes a few minutes (mostly compiling SQLite). Subsequent builds use the cargo cache and finish in seconds.\n\nThen plug it into the AI client of your choice — same shape for all of them, full [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md):\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop\u003c/b\u003e\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"heirloom\": { \"command\": \"heirloom\", \"args\": [\"serve\"] }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor\u003c/b\u003e\u003c/summary\u003e\n\n`Settings → MCP → Add new MCP server` — same JSON shape.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGoogle Antigravity\u003c/b\u003e\u003c/summary\u003e\n\n`Settings → Customizations → Open MCP Config` — paste the same snippet. Works alongside Antigravity's MCP store. See [`examples/mcp-antigravity.json`](examples/mcp-antigravity.json).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOpenClaw\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nopenclaw mcp add heirloom --command heirloom --args serve\n```\n\nOr drop [`examples/mcp-openclaw.json`](examples/mcp-openclaw.json) into your workspace `mcp.json`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code, Continue, Cline, Zed, Windsurf, custom agents\u003c/b\u003e\u003c/summary\u003e\n\nEvery MCP-aware client uses the same shape. See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) for per-client tweaks.\n\n\u003c/details\u003e\n\nRestart your client. Ask it something about your past. Watch it answer.\n\n## Ingesters\n\n| Name | Status | Description |\n|---|---|---|\n| `fs` | ✅ shipped | `.md` / `.txt` / `.rst` / `.org` files |\n| `browser` | ✅ shipped | Chrome / Brave / Arc / Edge / Vivaldi history (safe temp-copy read) |\n| `firefox` | ✅ shipped | Firefox `places.sqlite` history |\n| `claude` | ✅ shipped | Claude `conversations.json` export |\n| `chatgpt` | ✅ shipped | ChatGPT `conversations.json` export |\n| `claude-code` | ✅ shipped | Claude Code session transcripts |\n| `slack` | ✅ shipped | Slack workspace export (point at the unzipped directory) |\n| `obsidian` | ✅ shipped | Obsidian vault with frontmatter + wikilink metadata |\n| `antigravity` | 💡 wanted | Antigravity Manager-view artifacts |\n| `linear` | 💡 wanted | Linear issues + comments |\n| `apple-notes` | 💡 wanted | Apple Notes via JXA |\n| `kindle` | 💡 wanted | Kindle highlights + clippings |\n| `spotify` | 💡 wanted | Listening history |\n| `strava` | 💡 wanted | Workouts |\n| `letterboxd` | 💡 wanted | Films watched + reviews |\n\nBuild your own in ~50 lines — see [CONTRIBUTING.md](CONTRIBUTING.md) and copy `crates/ingesters/heirloom-fs` as a template.\n\n## Encryption at rest\n\nHeirloom uses **XChaCha20-Poly1305** authenticated encryption with an **Argon2id**-derived key (m=64 MiB, t=3, p=1) for the at-rest format.\n\n```bash\nHEIRLOOM_PASSPHRASE='correct horse battery staple' heirloom seal\n# heirloom.db is now heirloom.db.hlm (encrypted) and the plaintext is shredded\n\nHEIRLOOM_PASSPHRASE='correct horse battery staple' heirloom unseal\n# back to a working plaintext heirloom.db\n```\n\nSQLite needs random access, so Heirloom can't run with the file encrypted live. The `seal` / `unseal` workflow gives you real protection against offline attackers while keeping search latency at SQLite speed. See [SECURITY.md](SECURITY.md) for the full threat model.\n\n## Hybrid search\n\nPure FTS5 misses morphological variants (`postgres` ≠ `postgresql`, `auth` ≠ `authentication`). Pure transformer embeddings need ~80 MB of model + ONNX runtime. Heirloom ships a middle ground:\n\n- **BM25** for exact-keyword recall (from SQLite FTS5).\n- **Hash-projected n-gram TF-IDF vectors** for morphological + lexical similarity. Pure Rust, zero external models, embedded in the binary.\n\nThe `Embedder` trait in `heirloom-vector` is the seam — a future feature flag will let you swap in a `fastembed-rs` BERT-quality backend if you want transformer-grade recall and don't mind the deps.\n\n## Heirloom Teams — shared memory for your organization\n\nFor organizations that want to pool memories across team members, the v1.0 release ships **`heirloom-team-server`** — a self-hostable Rust binary you deploy on your own infrastructure. No SaaS account. No cloud lock-in. Your team's memories live on your hardware.\n\n```bash\n# On the server\nheirloom-team-server admin init --team-name \"Acme Engineering\"\n# → prints a bootstrap admin token\n\nheirloom-team-server --addr 0.0.0.0:7900\n# → server is up\n```\n\n```bash\n# On each member's machine\nheirloom team join http://team.acme.internal:7900 --token hlmt_…\nheirloom team sync         # push your shareable memories, pull the team's\n```\n\nHighlights:\n\n- **Bearer-token authentication.** Tokens are server-generated, scoped per member, revokable. Members never share tokens.\n- **End-to-end encrypted.** Memories are sealed client-side with the team passphrase before upload. The server stores only ciphertext.\n- **Comprehensive audit log.** Every read, write, and delete is recorded by actor, IP, and timestamp.\n- **Role-based access.** Admin / Member / Read-only.\n- **SQLite-backed.** Single binary, zero external services. Scales to several million memories without breaking a sweat.\n\nWhat's deferred to v1.1: OIDC/SAML SSO, Postgres backend for huge orgs, per-source ACLs. The current bearer-token model is the right honest tradeoff for v1.0 — many small orgs prefer it anyway. Architecture spec at [`docs/design/teams-architecture.md`](docs/design/teams-architecture.md).\n\n## Multi-device sync\n\nSingle-user sync across your own machines uses the same `.hlm v1` envelope:\n\n```bash\nheirloom sync status                                          # show device id + relay config\nHEIRLOOM_PASSPHRASE='...' heirloom sync push                  # produce encrypted snapshot at ~/.heirloom/snapshots/\nHEIRLOOM_PASSPHRASE='...' heirloom sync pull --from SNAP.hlm  # decrypt + merge into local store\n```\n\nEnd-to-end encrypted. Copy the `.hlm` between your devices over whatever transport you trust — Syncthing, AirDrop, USB stick, Dropbox, an S3 bucket you own. A hosted public relay (so you don't have to move the file yourself) is on the v1.1 roadmap; the full protocol spec is in [`docs/design/sync-protocol.md`](docs/design/sync-protocol.md).\n\n## Web viewer \u0026 desktop\n\n```\nheirloom viewer     # local dashboard at http://127.0.0.1:7878\nheirloom desktop    # same dashboard, opens in your default browser\n```\n\nSingle embedded HTML file. Dark theme. Keyboard shortcuts. One-click redact. No JavaScript framework. No analytics. No telemetry.\n\n## CLI\n\n```\nheirloom init                      Initialize a fresh memory store\nheirloom add \"...\"                 Add a memory directly\nheirloom ingest \u003cname\u003e [--path P]  Run an ingester\nheirloom search \"...\" [-k N]       Search the store\nheirloom recent [-s source]        Show newest memories\nheirloom serve                     Start the MCP server on stdio\nheirloom viewer [--addr A]         Start the local web viewer\nheirloom desktop                   Open the viewer in your default browser\nheirloom watch                     Start the auto-capture daemon\nheirloom seal                      Encrypt the database file\nheirloom unseal                    Decrypt the sealed database\nheirloom sync {status,push,…}      Encrypted multi-device sync\nheirloom export [-o FILE]          Export everything as JSONL\nheirloom redact --id \u003cuuid\u003e        Hard-delete a memory\nheirloom redact --query \"...\"      Delete every memory matching a query\nheirloom status                    Counts by source\nheirloom doctor                    Diagnose common issues\n\nheirloom-team-server               (separate binary) self-host team memory\n```\n\nAll commands accept `--json` for piping.\n\n## Auto-capture\n\n```toml\n# ~/.heirloom/config.toml\n[watch]\ninterval_minutes = 60\n\n[[watch.tasks]]\ningester = \"fs\"\npath = \"/Users/me/Documents/notes\"\n\n[[watch.tasks]]\ningester = \"browser\"\n\n[[watch.tasks]]\ningester = \"claude-code\"\n```\n\nThen `heirloom watch` and forget.\n\n## Privacy \u0026 security\n\n- **Local-first.** All data lives in `~/.heirloom/heirloom.db`. Nothing is uploaded by default.\n- **At-rest encryption.** XChaCha20-Poly1305 + Argon2id.\n- **No telemetry.** Heirloom does not phone home. Not even opt-in.\n- **Opt-in per source.** Ingesters run only when you invoke them or list them in `config.toml`.\n- **Redaction first.** Hard-delete via CLI or one-click in the viewer.\n- **Viewer binds to loopback only.** No LAN exposure.\n- **Team server is yours.** When you self-host `heirloom-team-server`, the bytes live on your hardware, with full audit logs.\n\nIf you find a security issue, please email `security@heirlooom.web.app` rather than filing a public issue.\n\n## Roadmap\n\n- [x] **v0.1** — Core, MCP server, 5 ingesters, CLI, web viewer, watch daemon, export\n- [x] **v0.2** — At-rest encryption, hybrid lexical+vector search, 3 more ingesters, desktop launcher, client-side sync pipeline\n- [x] **v1.0** — Self-hostable Heirloom Teams server with bearer auth, encrypted shared memory, role-based access, audit log\n- [ ] **v1.1** — Hosted reference relay for personal multi-device sync, OIDC/SAML SSO for Teams, Postgres backend option, optional BERT-quality embeddings (feature flag), Homebrew/debian/rpm packages\n- [ ] **v2.0** — Native desktop window (wry), Postgres + S3 backend for Teams at scale, per-source ACLs, hosted Heirloom Cloud option for orgs who don't want to operate the server\n\n## Contributing\n\nWe especially want **new ingesters**. They're the highest-leverage contribution and the design is intentionally tiny — you can ship one in an evening. Pick from the [wanted list](https://github.com/MayonaiseLover/heirloom/issues?q=is%3Aissue+label%3Aingester) or propose your own.\n\nFor everything else, see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE). Use it. Fork it. Build something on top of it.\n\n## Acknowledgments\n\nBuilt on [SQLite](https://www.sqlite.org), [rusqlite](https://github.com/rusqlite/rusqlite), [Tokio](https://tokio.rs), [chacha20poly1305 / argon2 (RustCrypto)](https://github.com/RustCrypto), and the [Model Context Protocol](https://modelcontextprotocol.io). Inspired by Vannevar Bush's [Memex](https://en.wikipedia.org/wiki/Memex), in spirit if not in mechanism.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmayonaiselover%2Fheirloom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmayonaiselover%2Fheirloom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmayonaiselover%2Fheirloom/lists"}