@percena/memfuse

SDK for MemFuse — the persistent memory hub for AI coding agents.

Installation

npm install @percena/memfuse

Prerequisites

MemFuse Server must be running. When you npm install @percena/memfuse, a postinstall hook automatically downloads the matching-version precompiled memfuse-server binary (for your platform) from GitHub Releases into ~/.memfuse/bin/. The binary version is locked to the installed SDK version — SDK 0.2.x fetches the v0.2.x binary.

The download never fails npm install: if it can't reach GitHub (airgap, proxy, or the release isn't published yet), it logs a hint and skips. Set MEMFUSE_SKIP_BINARY=1 to opt out entirely (e.g. CI that only needs the JS SDK). Retry manually any time:

npx --package=@percena/memfuse memfuse binary install
npx --package=@percena/memfuse memfuse binary doctor   # show cached path/version

You can also build from source:

cargo build --release -p mfs-server && ./target/release/memfuse-server

What's Included

| Component | Entry Point | Description | |-----------|-------------|-------------| | CLI | npx --package=@percena/memfuse memfuse | Full API surface; L0: setup / init / recall / save | | MCP Server | npx --package=@percena/memfuse memfuse-mcp | 16 Agent-facing tools via MCP protocol | | Setup Tool | npx --package=@percena/memfuse memfuse-setup | Deprecated; prefer memfuse init / memfuse setup | | Lifecycle Hooks | @percena/memfuse/hooks | 8 hooks for Claude Code, 3 for Codex | | HTTP Client | @percena/memfuse/client | Type-safe client for MemFuse Server API |

Quick Start

1. Start the service (machine once)

# Preferred: install + enable + start OS service
npx --package=@percena/memfuse memfuse setup

# Or foreground (no service):
npx --package=@percena/memfuse memfuse serve
# Verify: curl http://127.0.0.1:8720/health

2. Wire this repo for your agent (once per project)

cd my-app
npx --package=@percena/memfuse memfuse init

(memfuse-setup install still works but is deprecated in favor of memfuse init.)

3. Daily CLI

npx --package=@percena/memfuse memfuse recall "auth decisions"
npx --package=@percena/memfuse memfuse save "Found rate limiter config" --type Decision
npx --package=@percena/memfuse memfuse search "auth decisions" --strategy diverse
npx --package=@percena/memfuse memfuse facts
npx --package=@percena/memfuse memfuse health

Or install globally:

npm install -g @percena/memfuse
memfuse search "auth decisions"

4. Use as MCP Server

Add to your agent's MCP configuration:

{
  "mcpServers": {
    "memfuse": {
      "command": "npx",
      "args": ["--yes", "--package=@percena/memfuse", "memfuse-mcp"],
      "env": {
        "MEMFUSE_SERVER_URL": "http://localhost:8720",
        "MEMFUSE_USER_ID": "your-user-id"
      }
    }
  }
}

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | MEMFUSE_SERVER_URL | http://127.0.0.1:8720 | MemFuse Server URL (canonical default everywhere) | | MEMFUSE_USER_ID | default | User identifier |

Build (SDK contributors)

The SDK is built with tsc (not bundled into a single file). The subpath exports (./mcp, ./hooks, ./client) and the skills/ directory layout are consumed as files by Claude Code / Codex plugins, so that file-layout contract must be preserved — do not switch to a single-file bundler (esbuild/rollup) without revisiting the plugin contracts.

cd sdk && npm ci && npm run build

Links

• MemFuse Server — The Rust server
• Architecture — System design and crate structure
• User Guide — Detailed usage guide

License

MIT