memware

简体中文

Give AI agents long-term memory without making users repeat themselves.

memware is a local-first long-term memory layer for MCP-compatible agents. It distills conversations into durable, searchable memory and recalls relevant context in later tasks. Memory stays on the user's machine, while extraction and embedding use the OpenAI-compatible model endpoint the user chooses.

Status: pre-release. Source, tests, and local binary builds are available. Current source version 0.2.0. The npm package and GitHub Release are not public yet, so use the source path below today. npx memware will become available with the first public release.

Why memware

• Automatic writes: Stop-hook adapters capture each completed turn from Claude Code and Codex, so persistence does not depend on the model remembering to call a tool.

• Cross-agent task continuity: Every agent shares one local memory store; memory_resume hands an unfinished task to the next agent with its status, next step, and the last agent that touched it.

• On-demand recall: Eight MCP tools cover status, warmup, context retrieval, processing, search, task handoff, archive, and reset.

• Storage-free deployment option: When a host only needs extraction, embedding, and search and keeps its own storage, the stateless kernel service (src/kernel/) exposes those over HTTP and stores nothing itself.

• User-owned storage: Structured memory, vector indexes, and audit logs live under a local data directory.

• Provider choice: Extraction and embeddings use configurable OpenAI-compatible endpoints instead of a single locked provider.

flowchart LR
    A[User talks with an agent] --> B[Stop Hook captures the turn]
    B --> C[Extract durable facts and preferences]
    C --> D[(Local memory store)]
    E[New user request] --> F[MCP recall on demand]
    D --> F
    F --> G[Response grounded in prior context]

Related MCP server: Memory Crystal MCP Server

Try it today

The current source path requires Bun, Claude Code, and an API key for an OpenAI-compatible endpoint.

1. Clone, verify, and build

git clone https://github.com/HackSing/memware.git
cd memware
bun install
bun run test
bun run typecheck
bun run memware:build

2. Register the MCP server

Apple Silicon macOS:

claude mcp add memware \
  -e MEMWARE_API_KEY="$MEMWARE_API_KEY" \
  -- "$PWD/dist/memware/memware-darwin-arm64" serve

Linux x64:

claude mcp add memware \
  -e MEMWARE_API_KEY="$MEMWARE_API_KEY" \
  -- "$PWD/dist/memware/memware-linux-x64" serve

Windows x64:

claude mcp add memware \
  -e MEMWARE_API_KEY="$MEMWARE_API_KEY" \
  -- "$PWD/dist/memware/memware-windows-x64" serve

Call memory_status in Claude Code to verify the server. For a custom endpoint, also configure MEMWARE_BASE_URL, MEMWARE_MODEL, MEMWARE_EMBEDDING_MODEL, and the matching embedding dimension. Use MEMWARE_EMBEDDING_BASE_URL for a separate embedding endpoint and provide MEMWARE_EMBEDDING_API_KEY when it uses a different origin.

3. Enable automatic memory

Merge packages/memware/templates/claude-settings-hooks.json into the Claude Code settings, then add packages/memware/templates/claude-md-snippet.md to the project's CLAUDE.md. See the usage reference for configuration, all eight tools, and troubleshooting.

After the first npm release, installation will become:

claude mcp add memware -e MEMWARE_API_KEY=sk-... -- npx -y memware@latest serve

Updating

Source install (current):

cd memware
git pull
bun install
bun run test && bun run typecheck
bun run memware:build

Rebuilding overwrites the same dist/memware/<platform> binary your MCP registration points to, so new Claude Code sessions pick it up automatically — no need to re-run claude mcp add or change hook settings. Updates never touch the memory data under ~/.memware/. Check the Changelog before pulling; to roll back, git checkout <commit> and rebuild — the data directory is unaffected.

After the first npm release, npx -y memware@latest serve always resolves the newest published version (pin with memware@<version> when you need stability).

Use cases

memware is not a chat-history sync service, and it does not mean conversation text stays entirely on-device. Text used for extraction and embeddings is sent to the model endpoint you configure, while local userId and sessionId routing metadata is omitted from provider prompts. Choose that provider and deployment according to the sensitivity of your data.

Product boundaries

Documentation

• Usage reference: tools, configuration, data, and troubleshooting

• Content operations (Chinese): positioning, cadence, evidence gates, and metrics

• Architecture notes (Chinese): MCP surface, single write path, hook mode, and the stateless kernel service

• Kernel service contract: wire contract for /extract, /embed, and /search

• Contributing: issues, discussions, content, and code changes

• Security policy: supported state and private vulnerability reporting

• Changelog: user-visible changes and release state

Participate and stay updated

Use the entry point that matches the task:

• Report a reproducible problem with the Bug form.

• Propose a new product outcome with the Feature request form.

• Report missing or misleading docs with the Documentation form.

• Share use cases, tutorials, and questions in Discussions.

• Use GitHub Watch → Custom → Releases to receive meaningful release updates.

Development

bun run test
bun run typecheck
bun run content:check
bun run memware:build
bun run memware:pack
bun run kernel:serve
bun run kernel:build

memware is open-source software licensed under the MIT License. Copyright (c) 2026 Memware.