Real local memory engine + Claude Code plugin (v0.2)#1
Merged
Conversation
Take fast-mempalace from a demo with placeholder internals to a working, end-to-end-verified local memory engine for AI coding agents. Verified against Claude Code 2.1.191 (agent recalls memory-only facts via MCP with file tools disabled) and a 7/7 paraphrase retrieval test. Engine - embedder: real llama.cpp MiniLM-L6-v2 (384-dim) embeddings — encoder path (llama_encode), mean pooling, L2-normalized; was a constant dummy vector. Shared context guarded by an atomic spinlock for the concurrent miner. - build.zig: statically link the cmake-built llama.cpp/ggml .a archives via addObjectFile; previously pulled in Homebrew dylibs and crashed on a duplicate-dylib error. Pin the submodule to the verified-building commit. - miner: fix the directory walker — cmdMine used openFile to discriminate, which succeeds on directories in Zig 0.16's IO and mis-routed dirs to the conversation path (0 files mined). Now discriminates with openDir, adds a single-file document miner and an in-memory storeMemory path, and skips the palace's own .db/.db-wal/.db-shm files. - palace: serialize the content-insert -> lastInsertRowId -> vector-insert sequence with a write lock so the concurrent miner can't bind embeddings to the wrong drawer. - searcher: fix inverted hybrid scoring (closer match scored higher but was sorted ascending -> best result ranked last) and stop clamping distinct distances into ties. Agent integration - mcp: real MCP server with four tools (memory_search/store/wake_up/stats), lazy model load so initialize is instant, client protocol-version echo; was a hardcoded stub. - hooks: speak the real Claude Code protocol (hook_event_name). SessionStart injects the wake-up brief via additionalContext; PreCompact reads the transcript and auto-saves the recent tail before it's compacted away. Free the embedder before exit so ggml-metal's static destructor can't abort. - config: FAST_MEMPALACE_DB / _MODEL / _WING env overrides so the plugin can pin one global palace regardless of the project directory. Distribution - claude-plugin/ + .claude-plugin/marketplace.json: MCP server + SessionStart/ PreCompact hooks + using-memory skill + /remember and /recall commands. - install.sh: download a 384-dim MiniLM model (was nomic 768-dim, which mismatched the float[384] schema) and print the plugin install step. Docs - README: reposition around local-first memory for Claude Code; drop the "200x drop-in replacement" frame. - BENCHMARK: honest numbers for the real engine (the old 0.59s/1171-drawer figures measured placeholder vectors). - ROADMAP: mark shipped items. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- assets/demo.gif: 22s VHS-rendered demo of semantic recall (mine a repo, then ask in plain English and get the decision back). Embedded on the README's first screen. - docs/launch/show-hn.md: launch post for HN / r/LocalLLaMA / r/mcp — builder voice, reproducible numbers, title options. - docs/launch/demo.tape + demo/sample-project: reproducible source for the GIF. - docs/launch/README.md: the launch sequence and the three things that would sink it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- config: when the configured model path doesn't exist, fall back to ~/.fast-mempalace/lib/minilm.gguf so a brew/curl-installed binary works with zero config (the Homebrew wrapper still sets FAST_MEMPALACE_MODEL explicitly). - CI + release workflows: download the 384-dim MiniLM model (was nomic 768-dim, which mismatches the float[384] schema), add -DGGML_BLAS=ON on macOS so the libggml-blas.a that build.zig links actually exists, and extend the smoke test to mine + search (validates the real embedding path end to end). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…job) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Formula installs the per-platform release binary, bundles the 384-dim MiniLM model as a resource, and wraps the binary to pin FAST_MEMPALACE_MODEL so it works with zero config. scripts/update-tap.sh fills binary sha256s from a release and copies the formula into the tap repo. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…cleanup - The advertised MemPalace/fast-mempalace org/repo doesn't exist (404), so the install URL, plugin marketplace command, and clone URL were all broken. Point every github.com path at debpalash/fast-mempalace, where the code, the v0.2.0 release, and the plugin marketplace manifest actually live. Product name "Fast MemPalace" is unchanged. - install.sh: fix `tmp: unbound variable` at exit — the EXIT trap referenced a function-local var that was out of scope by the time it fired under `set -u`. Use a script-global TMP_DIR with one safe trap. Verified end-to-end against the live release: installs the binary + model and recalls correctly. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this is
Takes fast-mempalace from a demo with placeholder internals to a working, end-to-end-verified local memory engine for AI coding agents — and ships a Claude Code plugin.
Verified against Claude Code 2.1.191 on macOS (Apple Silicon, Metal): with file/web tools disabled, the agent recalled facts that exist only in the memory palace (e.g. a project's cart cap and a secret codename) purely through the
memory_searchMCP tool. Retrieval scores 7/7 top-1 on a paraphrase test.The problem it fixes
An audit found two of three advertised pillars were stubs:
tools/callreturned a hardcoded string;mine <dir>enumerated 0 files;Highlights
Engine
llama.cppMiniLM-L6-v2 (384-dim) embeddings — encoder path, mean pooling, L2-normalized; spinlock-guarded shared context for the concurrent miner..aarchives (genuine ~6 MB static binary, no dynamic llama/ggml).openDirdiscriminator), single-file document miner, self-DB skip.insert → lastInsertRowId → vector insert).Agent integration
memory_search/memory_store/memory_wake_up/memory_stats, lazy model load (instantinitialize), protocol-version echo.FAST_MEMPALACE_DB/_MODEL/_WINGenv overrides → one global palace from any project.Distribution
claude-plugin/+.claude-plugin/marketplace.json: MCP + hooks +using-memoryskill +/remember/recall.Docs
Notes for reviewers
lib/llama.cppsubmodule to the commit the FFI was written and verified against.src/main.zigkeeps an undocumentedembdbgsubcommand as a "verify your model" diagnostic.Test plan
zig build --release=fastandzig build testpass.cmake -S lib/llama.cpp -B lib/llama.cpp/build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DGGML_METAL=ON -DLLAMA_BUILD_TESTS=OFF -DLLAMA_BUILD_EXAMPLES=OFF -DLLAMA_BUILD_SERVER=OFF -DLLAMA_BUILD_TOOLS=OFF && cmake --build lib/llama.cpp/build -j.fast-mempalace mcp;claude plugin validate ./claude-pluginpasses.🤖 Generated with Claude Code