{"id":49959695,"url":"https://github.com/bunkerlab-net/mempalace","last_synced_at":"2026-05-18T01:40:00.987Z","repository":{"id":349806418,"uuid":"1203955027","full_name":"bunkerlab-net/mempalace","owner":"bunkerlab-net","description":"A Rust reimplementation of MemPalace/mempalace","archived":false,"fork":false,"pushed_at":"2026-05-15T22:58:49.000Z","size":936,"stargazers_count":52,"open_issues_count":3,"forks_count":10,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-05-16T01:19:22.463Z","etag":null,"topics":["ai","llm","mcp","memory","rust","sqlite","turso"],"latest_commit_sha":null,"homepage":"","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/bunkerlab-net.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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":"2026-04-07T14:49:20.000Z","updated_at":"2026-05-15T19:04:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bunkerlab-net/mempalace","commit_stats":null,"previous_names":["bunkerlab-net/mempalace"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bunkerlab-net/mempalace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bunkerlab-net%2Fmempalace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bunkerlab-net%2Fmempalace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bunkerlab-net%2Fmempalace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bunkerlab-net%2Fmempalace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bunkerlab-net","download_url":"https://codeload.github.com/bunkerlab-net/mempalace/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bunkerlab-net%2Fmempalace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33162128,"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":["ai","llm","mcp","memory","rust","sqlite","turso"],"created_at":"2026-05-18T01:40:00.060Z","updated_at":"2026-05-18T01:40:00.982Z","avatar_url":"https://github.com/bunkerlab-net.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mempalace\n\nA local-first memory palace for AI assistants. Single static binary backed by embedded SQLite (turso).\nNo Python, no ChromaDB, no API keys.\n\n**Drop-in replacement for [MemPalace/mempalace](https://github.com/MemPalace/mempalace) with a ~13MB binary instead of a ~100MB Python environment.**\n\n[![codecov](https://codecov.io/gh/bunkerlab-net/mempalace/graph/badge.svg)](https://codecov.io/gh/bunkerlab-net/mempalace)\n\n---\n\n## Why\n\nThe Python version used ChromaDB + SQLite. Under multiple simultaneous MCP clients,\nSQLite locking caused dropped writes. ChromaDB also carried a large dependency footprint\nand required Python to be installed.\n\nThis reimplementation:\n\n- Ships as a single self-contained binary\n- Replaces ChromaDB semantic search with a keyword inverted index (BM25-style scoring via `drawer_words`)\n- Fixes the concurrency problem at the turso layer\n- Keeps all MCP tools and all CLI commands fully compatible\n\n**Trade-off:** Keyword search instead of embedding-based semantic search.\nSemantic search is deferred until an embedded model is available without network dependencies.\n\n---\n\n## Installation\n\n```bash\ngit clone https://github.com/bunkerlab-net/mempalace.git\ncd mempalace\ncargo build --release\n# binary is at: target/release/mempalace\n```\n\nOptionally copy to a location on your PATH:\n\n```bash\ncp target/release/mempalace ~/.local/bin/mempalace\n```\n\n### Precompiled binaries (GitHub Actions Artifacts)\n\nEach artifact on the GitHub Actions page lists a `sha256` digest. Verify the\ndownloaded zip against that digest before extracting:\n\n```bash\n# macOS\nshasum -a 256 mempalace-macos-\u003cgit-short-sha\u003e.zip\n\n# Linux\nsha256sum mempalace-linux-\u003cgit-short-sha\u003e.zip\n```\n\nThe output should match the digest shown on the Artifacts page (strip the\nleading `sha256:` prefix before comparing).\n\nOn macOS, the extracted binary will also be quarantined because it was not\ndistributed through the App Store or a notarised installer. After extracting,\nremove the quarantine attribute before running:\n\n```bash\nxattr -d com.apple.quarantine ./mempalace\n```\n\n---\n\n## MCP Setup (Claude Code)\n\n```bash\nclaude mcp add mempalace -- /path/to/mempalace mcp\n```\n\nThe MCP server runs as a JSON-RPC 2.0 process over stdio. All 26 tools are available immediately\nafter the server starts.\n\nOn first use, call `mempalace_status` — it returns the full memory protocol and AAAK dialect spec\nin the response, so the AI learns how to use the palace during wake-up.\n\n---\n\n## Quick Start\n\n```bash\n# 1. Initialise a project (creates mempalace.yaml)\nmempalace init ~/my-project\n\n# 2. Mine project files into the palace\nmempalace mine ~/my-project\n\n# 3. Mine conversation transcripts\nmempalace mine ~/.claude/projects/ --mode convos\n\n# 4. Search\nmempalace search \"chromadb locking\"\n\n# 5. Generate wake-up context (L0 identity + L1 essential story)\nmempalace wake-up\n```\n\nSee [USAGE.md](USAGE.md) for the full CLI reference, configuration options, and MCP tool descriptions.\n\n---\n\n## Architecture\n\n```text\nsrc/\n  main.rs              Entry point: clap dispatch → open_palace() → handler\n  db.rs                open_db(), query_all() helpers over turso::Connection\n  schema.rs            DDL: 6 tables + indexes, ensure_schema()\n  config.rs            MempalaceConfig ($XDG_DATA_HOME/mempalace/config.json) + ProjectConfig (mempalace.yaml)\n  error.rs             thiserror Error enum\n\n  cli/                 One file per subcommand\n    init.rs            Entity discovery + optional LLM refinement + room detection → write mempalace.yaml\n    search.rs          CLI search output\n    wakeup.rs          L0 + L1 assembly and print\n    compress.rs        AAAK batch compression\n    split.rs           Mega-file session splitter\n    status.rs          Palace stats display\n    sync.rs            Gitignore-aware drawer prune (mempalace sync)\n    repair.rs          Backup + rebuild inverted index\n\n  llm/                 LLM provider abstraction (optional, used by init --llm)\n    client.rs          LlmProvider trait + Ollama / OpenAI-compat / Anthropic impls\n    refine.rs          Batched entity refinement: classify, drop, reclassify via LLM\n\n  palace/\n    miner.rs           Project file scanner + chunker + drawer writer; MineParams struct\n    convo_miner.rs     Conversation file scanner + normaliser + drawer writer\n    drawer.rs          add_drawer(), file_already_mined(), inverted index maintenance\n    chunker.rs         chunk_text(): 800-char chunks with 100-char overlap\n    search.rs          search_memories(): inverted index query with relevance scoring\n    room_detect.rs     70+ folder-to-room mappings, detect_room(), detect_rooms_from_folders()\n    query_sanitizer.rs 4-step sanitizer: strip system-prompt contamination from search queries\n    entities.rs        Shared DetectedEntity type used by entity_detect and project_scanner\n    entity_detect.rs   Person vs project heuristic classifier for prose files\n    entity_confirm.rs  Interactive / --yes entity confirmation UX\n    known_entities.rs  Global entity registry (~/.local/share/mempalace/known_entities.json)\n    project_scanner.rs Manifest parsing + git author scanning → DetectedDict\n    session_scanner.rs Claude Code project dir scanning for entity discovery\n    corpus_origin.rs   Heuristic + LLM detection of whether corpus is AI conversation\n    layers.rs          L0 identity + L1 essential story assembly\n    graph.rs           BFS traversal, auto-tunnel detection, explicit tunnel CRUD\n\n  kg/\n    mod.rs             Entity + triple CRUD\n    query.rs           query_entity(), kg_timeline()\n\n  normalize/           Chat export parsers → canonical transcript text\n    claude_code.rs     JSONL (Claude Code); strip_noise() removes UI chrome / system-reminder tags\n    claude_ai.rs       JSON array (Claude.ai) + privacy export format\n    codex.rs           JSONL (OpenAI Codex CLI)\n    chatgpt.rs         ChatGPT export JSON\n    slack.rs           Slack export JSON\n    gemini_cli.rs      Gemini CLI JSONL (detects via session_metadata sentinel)\n\n  dialect/             AAAK compression\n    mod.rs             compress(): header + content line assembly\n    emotions.rs        38 emotion codes, keyword → code mapping\n    topics.rs          Topic extraction with proper-noun frequency boost\n\n  extract/             Memory type classifier (used in general extraction mode)\n    mod.rs             5-type classifier: decision, preference, milestone, problem, emotional\n    markers.rs         ~80 regex patterns\n\n  mcp/\n    mod.rs             Async stdio JSON-RPC 2.0 event loop\n    protocol.rs        PALACE_PROTOCOL, AAAK_SPEC, 26 tool schemas (diary tools include optional wing)\n    tools.rs           Tool dispatch + all 26 handler implementations\n```\n\n---\n\n## Differences from mempalace-py\n\n| Area                           | Python                        | Rust                                |\n| ------------------------------ | ----------------------------- | ----------------------------------- |\n| Search                         | ChromaDB semantic / embedding | Keyword inverted index (BM25-style) |\n| `mempalace_search` score field | `similarity` (0–1 cosine)     | `similarity` (word hit count)       |\n| Storage                        | ChromaDB + SQLite             | Single turso (SQLite) file          |\n| Binary size                    | ~100MB Python env             | ~13MB binary                        |\n| Concurrency                    | SQLite locking issues         | WAL mode; resolved at turso layer   |\n| Duplicate detection            | 0.9 cosine threshold          | Keyword overlap threshold           |\n| Entity registry                | Wikipedia lookups             | Heuristic only (deferred)           |\n| Onboarding wizard              | Interactive                   | Interactive (`mempalace onboard`)   |\n| ChromaDB import                | N/A                           | Not implemented (deferred)          |\n| Gitignore support              | Full (projects)               | Full (`ignore` crate)               |\n| Repair command                 | Yes                           | Yes (`mempalace repair`)            |\n| Conversation formats           | Limited                       | Extended (+ Codex CLI, Gemini CLI)  |\n| MCP error responses            | Generic                       | Generic                             |\n| Query sanitizer                | Yes (issue #333)              | Yes (ported from mempalace-py)      |\n\n---\n\n## Code Style\n\nSee [STYLEGUIDE.md](STYLEGUIDE.md) for the full coding conventions: assertions,\nloop bounds, no-abbreviation naming, function length limits, clippy configuration,\nand the \"always say why\" comment rule.\n\n---\n\n## Tests\n\n```bash\ncargo nextest run\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbunkerlab-net%2Fmempalace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbunkerlab-net%2Fmempalace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbunkerlab-net%2Fmempalace/lists"}