Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
{
"name": "mempalace",
"owner": { "name": "MemPalace", "url": "https://github.com/debpalash" },
"name": "memxt",
"owner": { "name": "Yupcha", "url": "https://github.com/Yupcha" },
"metadata": {
"description": "Local-first memory for AI coding agents.",
"version": "0.2.0"
},
"plugins": [
{
"name": "fast-mempalace",
"name": "memxt",
"source": "./claude-plugin",
"description": "Persistent, private, local memory for Claude Code — your agent remembers your code and decisions across sessions. One static binary, no cloud. Requires the fast-mempalace binary (curl install).",
"description": "Persistent, private, local memory for Claude Code — your agent remembers your code and decisions across sessions. One static binary, no cloud. Requires the memxt binary (curl install).",
"version": "0.2.0",
"license": "MIT",
"keywords": ["memory", "local-first", "mcp", "privacy"]
Expand Down
10 changes: 5 additions & 5 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -119,11 +119,11 @@ jobs:
- name: Execute CLI Validation (incl. real embeddings)
run: |
set -eux
./zig-out/bin/fast-mempalace init
./zig-out/bin/fast-mempalace stats
./zig-out/bin/memxt init
./zig-out/bin/memxt stats
printf 'The deploy key id is QUASAR-77 and must never be logged.\n' > smoke.txt
./zig-out/bin/fast-mempalace mine smoke.txt smoke
./zig-out/bin/fast-mempalace search "what is the deploy key" 2>&1 | grep -q QUASAR-77
./zig-out/bin/memxt mine smoke.txt smoke
./zig-out/bin/memxt search "what is the deploy key" 2>&1 | grep -q QUASAR-77

- name: Integration tests (mine / ranking / MCP / hooks / schema)
run: bash scripts/integration-test.sh ./zig-out/bin/fast-mempalace
run: bash scripts/integration-test.sh ./zig-out/bin/memxt
20 changes: 10 additions & 10 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -115,29 +115,29 @@ jobs:
- name: Smoke test (incl. real embeddings)
run: |
set -eux
./zig-out/bin/fast-mempalace init
./zig-out/bin/fast-mempalace stats
./zig-out/bin/memxt init
./zig-out/bin/memxt stats
# Validate the full semantic path: mine a file, then recall it.
printf 'The deploy key id is QUASAR-77 and must never be logged.\n' > smoke.txt
./zig-out/bin/fast-mempalace mine smoke.txt smoke
./zig-out/bin/fast-mempalace search "what is the deploy key" 2>&1 | grep -q QUASAR-77
./zig-out/bin/memxt mine smoke.txt smoke
./zig-out/bin/memxt search "what is the deploy key" 2>&1 | grep -q QUASAR-77

- name: Package tarball
env:
TARGET: ${{ matrix.target }}
run: |
TARBALL="fast-mempalace-${TARGET}.tar.gz"
tar -czf "$TARBALL" -C zig-out/bin fast-mempalace
TARBALL="memxt-${TARGET}.tar.gz"
tar -czf "$TARBALL" -C zig-out/bin memxt
shasum -a 256 "$TARBALL" > "$TARBALL.sha256"
ls -lh "$TARBALL" "$TARBALL.sha256"

- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: fast-mempalace-${{ matrix.target }}
name: memxt-${{ matrix.target }}
path: |
fast-mempalace-${{ matrix.target }}.tar.gz
fast-mempalace-${{ matrix.target }}.tar.gz.sha256
memxt-${{ matrix.target }}.tar.gz
memxt-${{ matrix.target }}.tar.gz.sha256

release:
name: Publish GitHub Release
Expand All @@ -164,7 +164,7 @@ jobs:
Install with one line:

```bash
curl -fsSL https://raw.githubusercontent.com/MemPalace/fast-mempalace/main/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/Yupcha/memxt/main/install.sh | bash
```

Prebuilt binaries attached for darwin-aarch64, darwin-x86_64, linux-x86_64, linux-aarch64.
4 changes: 2 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ zig-out/
.zig-cache/

# Executables
fast-mempalace
memxt
mempalace

# IDE / OS
Expand All @@ -27,7 +27,7 @@ lib/*.gguf
lib/llama.cpp/build/

# External Configs mapping over default parameters
fast-mempalace.yaml
memxt.yaml
mempalace.yaml
lib/llama.cpp
.claude/
16 changes: 8 additions & 8 deletions BENCHMARK.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# ⏱️ fast-mempalace Benchmarks
# ⏱️ memxt Benchmarks

Absolute performance of the real semantic engine (`llama.cpp` MiniLM-L6-v2 embeddings +
`sqlite-vec`). Hardware: Apple Silicon, macOS, Metal backend. Each command run cold
Expand Down Expand Up @@ -47,14 +47,14 @@ unrelated topics ~0.03.
zig build --release=fast

# point at a 384-dim model
export FAST_MEMPALACE_MODEL=$PWD/lib/minilm.gguf
export FAST_MEMPALACE_DB=/tmp/bench.db
export MEMXT_MODEL=$PWD/lib/minilm.gguf
export MEMXT_DB=/tmp/bench.db

./zig-out/bin/fast-mempalace init
/usr/bin/time -p ./zig-out/bin/fast-mempalace mine ./src bench # mine a directory
/usr/bin/time -p ./zig-out/bin/fast-mempalace search "how does search ranking work"
/usr/bin/time -p ./zig-out/bin/fast-mempalace wake-up
./zig-out/bin/memxt init
/usr/bin/time -p ./zig-out/bin/memxt mine ./src bench # mine a directory
/usr/bin/time -p ./zig-out/bin/memxt search "how does search ranking work"
/usr/bin/time -p ./zig-out/bin/memxt wake-up
```

For warm MCP-server latency, start `fast-mempalace mcp` and issue repeated
For warm MCP-server latency, start `memxt mcp` and issue repeated
`tools/call → memory_search` requests over stdio; only the first pays the model-load cost.
6 changes: 3 additions & 3 deletions Dockerfile.ci
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Dockerfile.ci — local mirror of the Ubuntu GitHub Actions build matrix.
#
# Usage:
# docker build -f Dockerfile.ci -t fast-mempalace-ci .
# docker run --rm fast-mempalace-ci
# docker build -f Dockerfile.ci -t memxt-ci .
# docker run --rm memxt-ci
#
# Or via the helper:
# ./scripts/ci-local.sh
Expand Down Expand Up @@ -89,4 +89,4 @@ RUN find lib/llama.cpp/build -name '*.a' -print | head -20 \

RUN zig build --release=fast

CMD ["sh", "-c", "./zig-out/bin/fast-mempalace init && ./zig-out/bin/fast-mempalace stats"]
CMD ["sh", "-c", "./zig-out/bin/memxt init && ./zig-out/bin/memxt stats"]
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2026 debpalash
Copyright (c) 2026 Yupcha

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
52 changes: 26 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
<div align="center">
<img src="assets/logo.svg" alt="Fast MemPalace Logo" width="350"/>
<h1>fast-mempalace</h1>
<img src="assets/logo.svg" alt="memxt Logo" width="350"/>
<h1>memxt</h1>
<p><b>Local-first long-term memory for AI coding agents.</b><br/>
Your agent remembers your codebase and decisions across sessions — in a single static binary. No cloud, no Python, nothing leaves your machine.</p>
<br/>
<img src="assets/demo.gif" alt="fast-mempalace semantic recall demo" width="760"/>
<img src="assets/demo.gif" alt="memxt semantic recall demo" width="760"/>
</div>

---

Most AI coding sessions start amnesiac: you re-explain the architecture, re-state why
you chose SQLite over Postgres, and the agent still contradicts last week's decision.
**fast-mempalace** gives the agent a persistent, on-device memory it can search and
**memxt** gives the agent a persistent, on-device memory it can search and
write to — wired into Claude Code via MCP tools and session hooks.

- 🧠 **Remembers across sessions** — semantic recall over everything you've mined or saved.
Expand All @@ -22,20 +22,20 @@ write to — wired into Claude Code via MCP tools and session hooks.
## ⚡ Install

```bash
curl -fsSL https://raw.githubusercontent.com/debpalash/fast-mempalace/main/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/Yupcha/memxt/main/install.sh | bash
```

Detects `darwin|linux` × `x86_64|aarch64`. Binary + embedding model land in
`~/.fast-mempalace/`.
`~/.memxt/`.

## 🤖 Use with Claude Code (the main event)

Install the plugin — it wires up the MCP memory tools, the session hooks, a skill, and
slash commands:

```text
/plugin marketplace add debpalash/fast-mempalace
/plugin install fast-mempalace
/plugin marketplace add Yupcha/memxt
/plugin install memxt
```

You now have:
Expand All @@ -52,11 +52,11 @@ You now have:
Optionally seed memory from a codebase:

```bash
~/.fast-mempalace/bin/fast-mempalace mine . my-project
~/.memxt/bin/memxt mine . my-project
```

> Works with any MCP client (Cursor, Zed, Windsurf, …) too — point it at
> `fast-mempalace mcp`.
> `memxt mcp`.

## 🧩 How it works

Expand Down Expand Up @@ -89,30 +89,30 @@ Apple Silicon · Metal · cold process unless noted. Methodology →
## 📦 CLI

```text
fast-mempalace init Initialize the palace database
fast-mempalace mine <path> [wing] Mine a file or directory into the palace
fast-mempalace search <query> Semantic search
fast-mempalace wake-up [--wing X] Print the wake-up context
fast-mempalace stats Palace statistics
fast-mempalace mcp Start the MCP server (stdio JSON-RPC)
fast-mempalace hook Run a Claude Code hook (JSON stdin/stdout)
fast-mempalace kg [subject] Query the knowledge graph
memxt init Initialize the palace database
memxt mine <path> [wing] Mine a file or directory into the palace
memxt search <query> Semantic search
memxt wake-up [--wing X] Print the wake-up context
memxt stats Palace statistics
memxt mcp Start the MCP server (stdio JSON-RPC)
memxt hook Run a Claude Code hook (JSON stdin/stdout)
memxt kg [subject] Query the knowledge graph
```

## ⚙️ Configuration

Reads `fast-mempalace.yaml` (falls back to `mempalace.yaml`). Environment variables
Reads `memxt.yaml` (falls back to `mempalace.yaml`). Environment variables
override everything — this is how the plugin pins one global palace regardless of the
project directory:

```bash
FAST_MEMPALACE_DB=~/.fast-mempalace/palace.db # database path
FAST_MEMPALACE_MODEL=~/.fast-mempalace/lib/minilm.gguf # 384-dim GGUF embedder
FAST_MEMPALACE_WING=my-project # default wing
MEMXT_DB=~/.memxt/palace.db # database path
MEMXT_MODEL=~/.memxt/lib/minilm.gguf # 384-dim GGUF embedder
MEMXT_WING=my-project # default wing
```

```yaml
database_path: "fast-mempalace.db"
database_path: "memxt.db"
model_path: "lib/minilm.gguf"
default_wing: "production"
```
Expand All @@ -125,8 +125,8 @@ The embedding model must be **384-dim** (MiniLM-L6-v2); the vector table is decl
Needs `zig 0.16.0` + `cmake`.

```bash
git clone --recursive https://github.com/debpalash/fast-mempalace
cd fast-mempalace
git clone --recursive https://github.com/Yupcha/memxt
cd memxt

# 1) Build the statically-linked llama.cpp backend (once)
cmake -S lib/llama.cpp -B lib/llama.cpp/build \
Expand All @@ -141,7 +141,7 @@ mkdir -p lib && curl -L -o lib/minilm.gguf \

# 3) Build
zig build --release=fast
./zig-out/bin/fast-mempalace stats
./zig-out/bin/memxt stats
```

(On Linux, use `-DGGML_METAL=OFF -DGGML_BLAS=OFF`.)
Expand Down
20 changes: 10 additions & 10 deletions ROADMAP.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 🗺️ Roadmap — Parity & Outmatch

Path from `fast-mempalace` today to **full drop-in parity** with the upstream Python `mempalace` package, then to **outmatching** it with capabilities the Python stack cannot reach.
Path from `memxt` today to **full drop-in parity** with the upstream Python `mempalace` package, then to **outmatching** it with capabilities the Python stack cannot reach.

Legend: `[x]` done · `[~]` partial · `[ ]` planned

Expand All @@ -19,10 +19,10 @@ against Claude Code 2.1.191.
- [x] `wake-up [--wing X]` — L0+L1 context loader (~600–900 tok)
- [x] **`mcp` — real MCP server**: `memory_search` / `memory_store` / `memory_wake_up` / `memory_stats`, lazy model load, protocol-version echo (was a hardcoded stub)
- [x] **`hook` — real Claude Code protocol**: SessionStart injects wake-up via `additionalContext`; PreCompact reads the transcript and **auto-saves** the tail (was a custom protocol + a nag)
- [x] **Claude Code plugin** — `claude-plugin/` + marketplace manifest: MCP server + hooks + `using-memory` skill + `/remember` `/recall` commands; one global palace via `FAST_MEMPALACE_DB`/`_MODEL` env overrides
- [x] **Claude Code plugin** — `claude-plugin/` + marketplace manifest: MCP server + hooks + `using-memory` skill + `/remember` `/recall` commands; one global palace via `MEMXT_DB`/`_MODEL` env overrides
- [x] `kg [subject]` — knowledge-graph relationship query (manual population)
- [x] `instructions` — memory-instruction emitter
- [x] `mempalace.yaml` + `fast-mempalace.yaml` config + env-var overrides
- [x] `mempalace.yaml` + `memxt.yaml` config + env-var overrides
- [x] MIT license, GitHub Actions CI, one-line curl installer (now fetches a **384-dim** model)
- [x] Honest benchmarks vs the real engine (`BENCHMARK.md`); retrieval 7/7 top-1 on a paraphrase test

Expand All @@ -40,13 +40,13 @@ Close every remaining gap with the upstream `pip install mempalace` surface. Eac
- [ ] **`init` vs `stats`** — upstream uses `init`; alias our `stats` where appropriate
- [ ] **Incremental re-mining** — content-hash skip for unchanged files (currently re-embeds all)
- [ ] **`forget <id|wing>`** — evict drawers
- [ ] **Export / import** — `fast-mempalace export <path>` JSONL dump + re-ingest round-trip
- [ ] **Export / import** — `memxt export <path>` JSONL dump + re-ingest round-trip
- [ ] **Ignore-pattern parity** — `.gitignore`-style globs matching upstream semantics
- [ ] **Config schema audit** — every upstream yaml key respected or rejected with a diagnostic
- [ ] **Python-parity output strings** — exit codes, stderr format, progress-bar layout for script consumers
- [ ] **Embedding model swap** — allow upstream's default model name via `model: <name>` resolving to HF URL

**Definition of done:** a user can `pip uninstall mempalace && curl ... | bash && ln -s .../fast-mempalace .../mempalace` and every script in their pipeline keeps working unchanged.
**Definition of done:** a user can `pip uninstall mempalace && curl ... | bash && ln -s .../memxt .../mempalace` and every script in their pipeline keeps working unchanged.

---

Expand All @@ -59,23 +59,23 @@ Ship features upstream Python cannot match without rewriting. Each lands a capab
- [ ] **Batched embedding kernel** — vectorize mine across N files per GPU call (target: 10× mine throughput vs current 200×)
- [ ] **Incremental vector index** — sqlite-vec HNSW params tuned per drawer-count bucket
- [ ] **Zero-copy mmap ingest** — large file mining without full read-into-RAM
- [ ] **Compile-time schema** — Zig comptime validation of `fast-mempalace.yaml`; bad config fails at build, not runtime
- [ ] **Compile-time schema** — Zig comptime validation of `memxt.yaml`; bad config fails at build, not runtime

### v0.4 — Reach Beyond CLI

- [ ] **Watch mode** — `fast-mempalace watch <path>` file-system events → auto re-mine (upstream Python blocks on ChromaDB lock; we don't)
- [ ] **Embedded HTTP API** — `fast-mempalace serve --port 8080` pure Zig handler, <5 MB RAM overhead
- [ ] **Watch mode** — `memxt watch <path>` file-system events → auto re-mine (upstream Python blocks on ChromaDB lock; we don't)
- [ ] **Embedded HTTP API** — `memxt serve --port 8080` pure Zig handler, <5 MB RAM overhead
- [ ] **Web UI** — single-file static dashboard shipped inside binary (SQLite browser + search box)
- [ ] **Hybrid search** — BM25 + vector fusion (upstream is vector-only)
- [ ] **Time-scoped queries** — `--since 2026-01-01`, `--until`, decay-weighted ranking

### v0.5 — Ecosystem & Distribution

- [ ] **Homebrew formula** — `brew install fast-mempalace`
- [ ] **Homebrew formula** — `brew install memxt`
- [ ] **Docker image** — ~15 MB distroless image (vs upstream ~1.2 GB Python+ML)
- [ ] **Shell completions** — zsh / bash / fish
- [x] **Claude Code plugin** — `claude-plugin/` wires MCP + hooks + skill + slash commands (v0.2)
- [ ] **Plugin SDK** — stable `lib/fast_mempalace.h` C ABI for 3rd-party languages
- [ ] **Plugin SDK** — stable `lib/memxt.h` C ABI for 3rd-party languages

### v0.6+ — Intelligence Layer

Expand Down
Binary file modified assets/demo.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions build.zig
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ pub fn build(b: *std.Build) void {

// ── Main executable ──
const exe = b.addExecutable(.{
.name = "fast-mempalace",
.name = "memxt",
.root_module = b.createModule(.{
.root_source_file = b.path("src/main.zig"),
.target = target,
Expand All @@ -25,7 +25,7 @@ pub fn build(b: *std.Build) void {
run_cmd.step.dependOn(b.getInstallStep());
if (b.args) |args| run_cmd.addArgs(args);

const run_step = b.step("run", "Run fast-mempalace");
const run_step = b.step("run", "Run memxt");
run_step.dependOn(&run_cmd.step);

// ── Tests ──
Expand Down
4 changes: 2 additions & 2 deletions build.zig.zon
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.{
.name = .fast_mempalace,
.name = .memxt,
.version = "0.1.0",
.fingerprint = 0x182ae31931ffe1cb,
.fingerprint = 0x5bf95d78bca15787,
.minimum_zig_version = "0.16.0",
.paths = .{
"build.zig",
Expand Down
10 changes: 5 additions & 5 deletions claude-plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "fast-mempalace",
"displayName": "Fast MemPalace — Local Memory",
"name": "memxt",
"displayName": "memxt — Local Memory",
"version": "0.2.0",
"description": "Persistent, private, local-first memory for Claude Code. Your agent remembers your code and decisions across sessions — one static binary, no cloud, nothing leaves your machine.",
"author": { "name": "MemPalace", "url": "https://github.com/debpalash" },
"homepage": "https://github.com/debpalash/fast-mempalace",
"repository": "https://github.com/debpalash/fast-mempalace",
"author": { "name": "Yupcha", "url": "https://github.com/Yupcha" },
"homepage": "https://github.com/Yupcha/memxt",
"repository": "https://github.com/Yupcha/memxt",
"license": "MIT",
"keywords": ["memory", "mcp", "local-first", "claude-code", "embeddings", "privacy"],
"mcpServers": "./.mcp.json",
Expand Down
Loading
Loading