Loading plugin...

claude-mem · Flowy

README

Quick Start

Install with a single command:

npx claude-mem install

Or install for OpenCode:

npx claude-mem install --ide opencode

Or install for Antigravity CLI (setup guide):

npx claude-mem install --ide antigravity

Or install from the plugin marketplace inside Claude Code:

/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

Restart Claude Code. Context from previous sessions will automatically appear in new sessions.

Note: Claude-Mem is also published on npm, but npm install -g claude-mem installs the SDK/library only — it does not register the plugin hooks or set up the worker service. Always install via npx claude-mem install or the /plugin commands above.

🦞 OpenClaw Gateway

Install claude-mem as a persistent memory plugin on OpenClaw gateways with a single command:

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

The installer handles dependencies, plugin setup, AI provider configuration, worker startup, and optional real-time observation feeds to Telegram, Discord, Slack, and more. See the OpenClaw Integration Guide for details.

Key Features:

🧠 Persistent Memory - Context survives across sessions
📊 Progressive Disclosure - Layered memory retrieval with token cost visibility
🔍 Skill-Based Search - Query your project history with mem-search skill
🖥️ Web Viewer UI - Real-time memory stream at the worker URL printed on startup
💻 Claude Desktop Skill - Search memory from Claude Desktop conversations
🔒 Privacy Control - Use <private> tags to exclude sensitive content from storage
⚙️ Context Configuration - Fine-grained control over what context gets injected
🤖 Automatic Operation - No manual intervention required
🔗 Citations - Reference past observations with IDs through the worker API or view all in the web viewer

Documentation

📚 View Full Documentation - Browse on official website

Getting Started

Installation Guide - Quick start & advanced installation
Usage Guide - How Claude-Mem works automatically
Search Tools - Query your project history with natural language
Cloud Sync - Back up your memories to cmem.ai — no daemon, the worker syncs on write

Best Practices

Context Engineering - AI agent context optimization principles
Progressive Disclosure - Philosophy behind Claude-Mem's context priming strategy

Architecture

Overview - System components & data flow
Architecture Evolution - The journey from v3 to v5
Hooks Architecture - How Claude-Mem uses lifecycle hooks
Hooks Reference - 7 hook scripts explained
Worker Service - HTTP API & Bun management
Database - SQLite schema & FTS5 search
Search Architecture - Hybrid search with Chroma vector database

Configuration & Development

Configuration - Environment variables & settings
Development - Building, testing, contributing
Release Branches - Stable, core-dev, and community-edge branch flow
Troubleshooting - Common issues & solutions

How It Works

Core Components:

5 Lifecycle Hooks - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
Smart Install - Cached dependency checker (pre-hook script, not a lifecycle hook)
Worker Service - Local HTTP API with web viewer UI and search endpoints, managed by Bun
SQLite Database - Stores sessions, observations, summaries
mem-search Skill - Natural language queries with progressive disclosure
Chroma Vector Database - Hybrid semantic + keyword search for intelligent context retrieval

See Architecture Overview for details.

MCP Search Tools

Claude-Mem provides intelligent memory search through 4 MCP tools following a token-efficient 3-layer workflow pattern:

The 3-Layer Workflow:

search - Get compact index with IDs (~50-100 tokens/result)
timeline - Get chronological context around interesting results
get_observations - Fetch full details ONLY for filtered IDs (~500-1,000 tokens/result)

How It Works:

Claude uses MCP tools to search your memory
Start with search to get an index of results
Use timeline to see what was happening around specific observations
Use get_observations to fetch full details for relevant IDs
~10x token savings by filtering before fetching details

Available MCP Tools:

search - Search memory index with full-text queries, filters by type/date/project
timeline - Get chronological context around a specific observation or query
get_observations - Fetch full observation details by IDs (always batch multiple IDs)

Example Usage:

// Step 1: Search for index
search(query="authentication bug", type="bugfix", limit=10)

// Step 2: Review index, identify relevant IDs (e.g., #123, #456)

// Step 3: Fetch full details
get_observations(ids=[123, 456])

See Search Tools Guide for detailed examples.

Release Branches

Stable releases ship from main and are published to npm. core-dev and community-edge are source-run branches for early reliability fixes and community integrations. See Release Branches for the branch flow and non-stable run instructions.

System Requirements

Node.js: 20.0.0 or higher
Claude Code: Latest version with plugin support
Bun: JavaScript runtime and process manager (auto-installed if missing)
uv: Python package manager for vector search (auto-installed if missing)
SQLite 3: For persistent storage (bundled)

Windows Setup Notes

If you see an error like:

npm : The term 'npm' is not recognized as the name of a cmdlet

Make sure Node.js and npm are installed and added to your PATH. Download the latest Node.js installer from https://nodejs.org and restart your terminal after installation.

Configuration

Settings are managed in ~/.claude-mem/settings.json (auto-created with defaults on first run). Configure AI model, worker port, data directory, log level, and context injection settings.

See the Configuration Guide for all available settings and examples.

Mode & Language Configuration

Claude-Mem supports multiple workflow modes and languages via the CLAUDE_MEM_MODE setting.

This option controls both:

The workflow behavior (e.g. code, chill, investigation)
The language used in generated observations

How to Configure

Edit your settings file at ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_MODE": "code--zh"
}

Modes are defined in plugin/modes/. To see all available modes locally:

ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/

Available Modes

Mode	Description
`code`	Default English mode
`code--zh`	Simplified Chinese mode
`code--ja`	Japanese mode

Language-specific modes follow the pattern code--[lang] where [lang] is the ISO 639-1 language code (e.g., zh for Chinese, ja for Japanese, es for Spanish).

Note: code--zh (Simplified Chinese) is already built-in — no additional installation or plugin update is required.

After Changing Mode

Restart Claude Code to apply the new mode configuration.

Development

See the Development Guide for build instructions, testing, and contribution workflow.

Troubleshooting

If experiencing issues, describe the problem to Claude and the troubleshoot skill will automatically diagnose and provide fixes.

See the Troubleshooting Guide for common issues and solutions.

Bug Reports

Create comprehensive bug reports with the automated generator:

cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Update documentation
Submit a Pull Request

Claude-Mem ships from three branches: main (stable), core-dev, and community-edge. Only main is published to npm; the others are run from source. See Release Branches for the strategy and local run instructions.

See Development Guide for contribution workflow.

License

Claude-Mem is licensed under the Apache License 2.0.

We chose Apache-2.0 because durable agentic memory should be easy to embed in developer tools, local agents, MCP servers, enterprise systems, robotics stacks, and production agent harnesses.

See the LICENSE file for full details. See docs/license.md and docs/ip-boundary.md for licensing scope and the open/commercial boundary.

Note on Ragtime: The ragtime/ directory is licensed under the Apache License 2.0. See ragtime/LICENSE for details.

Support

Documentation: docs/
Issues: GitHub Issues
Repository: github.com/thedotmack/claude-mem
Official X Account: @Claude_Memory
Official Discord: Join Discord
Author: Alex Newman (@thedotmack)

Built with Claude Agent SDK | Works with Claude Code | Made with TypeScript

What About CMEM?

CMEM is a token created by a 3rd party but officially embraced by the creator of Claude-Mem (Alex Newman, @thedotmack). The token acts as a community catalyst for growth and a vehicle for bringing CMEM to the developers and knowledge workers that need it most.

Official BASE CA: 0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3

File tree

940

thedotmack/claude-memView on GitHub ↗

.agent/
  rules/
    claude-mem-context.md
.agents/
  plugins/
    marketplace.json
.claude/
.claude-plugin/
  marketplace.json
  plugin.json
  commands/
    anti-pattern-czar.md
  plans/
    animated-installer.md
  reports/
    test-audit-2026-01-05.md
  settings.json
.codex-plugin/
  plugin.json
.dockerignore
.gitattributes
.github/
  copilot-instructions.md
  FUNDING.yml
  ISSUE_TEMPLATE/
    bug_report.md
    feature_request.md
  workflows/
    ci.yml
    claude.yml
    close-tracked-issues.yml
    convert-feature-requests.yml
    deploy-install-scripts.yml
    npm-publish.yml
    summary.yml
    windows.yml
.gitignore
.markdownlint.json
.npmignore
.npmrc
.plan/
  issue-2341-reliability-slice.md
  npx-distribution.md
  subagent-summary-disable-and-labeling.md
  worktree-adoption.md
.translation-cache.json
.windsurf/
  rules/
    claude-mem-context.md
bunfig.toml
CHANGELOG.md
CLAUDE.md
cursor-hooks/
  .gitignore
  CONTEXT-INJECTION.md
  cursorrules-template.md
  hooks.json
  INTEGRATION.md
  PARITY.md
  QUICKSTART.md
  README.md
  REVIEW.md
  STANDALONE-SETUP.md
docker/
docker-compose.e2e.yml
docker-compose.yml
  claude-mem/
    build.sh
    Dockerfile
    entrypoint.sh
    README.md
    run.sh
  e2e/
    server-e2e.mjs
Dockerfile.test-installer
docs/
  adapters.md
  anti-pattern-cleanup-plan.md
  api.md
  architecture-overview.md
  assets/
    merge-clinic/
      slide-01.jpg
      slide-02.jpg
      slide-03.jpg
      slide-04.jpg
      slide-05.jpg
      slide-06.jpg
      slide-07.jpg
      slide-08.jpg
      slide-09.jpg
      slide-10.jpg
      slide-11.jpg
      slide-12.jpg
      slide-13.jpg
      slide-14.jpg
      slide-15.jpg
  bug-fixes/
    windows-spaces-issue.md
  context/
    agent-sdk-v2-examples.ts
    agent-sdk-v2-preview.md
    cursor-hooks-reference.md
  docker.md
  i18n/
    .translation-cache.json
    README.ar.md
    README.bn.md
    README.cs.md
    README.da.md
    README.de.md
    README.el.md
    README.es.md
    README.fi.md
    README.fr.md
    README.he.md
    README.hi.md
    README.hu.md
    README.id.md
    README.it.md
    README.ja.md
    README.ko.md
    README.nl.md
    README.no.md
    README.pl.md
    README.pt-br.md
    README.pt.md
    README.ro.md
    README.ru.md
    README.sv.md
    README.th.md
    README.tl.md
    README.tr.md
    README.uk.md
    README.ur.md
    README.vi.md
    README.zh-tw.md
    README.zh.md
  ip-boundary.md
  license.md
  merge-rubric.md
  migration-worker-to-server.md
  production-guide.md
  public/
    antigravity-cli/
      setup.mdx
    architecture/
    architecture-evolution.mdx
      database.mdx
      hooks.mdx
      overview.mdx
      pm2-to-bun-migration.mdx
      search-architecture.mdx
      worker-service.mdx
    branches.mdx
    claude-mem-logo-for-dark-mode.webp
    claude-mem-logo-for-light-mode.webp
    claude-mem-logomark.webp
    cloud-sync.mdx
    cm-preview.gif
    configuration/
    configuration.mdx
      custom-anthropic-backends.mdx
      litellm-gateway.mdx
    context-engineering.mdx
    cursor/
      gemini-setup.mdx
      index.mdx
      openrouter-setup.mdx
    development.mdx
    docs.json
    file-read-gate.mdx
    hooks-architecture.mdx
    hosted-server.mdx
    installation.mdx
    introduction.mdx
    modes.mdx
    openclaw-integration.mdx
    platform-integration.mdx
    progressive-disclosure.mdx
    smart-explore-benchmark.mdx
    telemetry.mdx
    trendshift-badge-dark.svg
    trendshift-badge.svg
    troubleshooting.mdx
    usage/
      claude-desktop.mdx
      export-import.mdx
      folder-context.mdx
      gemini-provider.mdx
      getting-started.mdx
      knowledge-agents.mdx
      manual-recovery.mdx
      openrouter-provider.mdx
      private-tags.mdx
      search-tools.mdx
  security.md
  server-architecture-and-team-vision.md
  server-parity-map.md
  server-release-readiness.md
  server-storage-boundary.md
  server.md
  SESSION_ID_ARCHITECTURE.md
fixtures/
  tpuf-content-v2.json
install/
  .gitignore
  public/
    install.sh
    installer.js
  vercel.json
LICENSE
NOTICE
openclaw/
  .gitignore
  .npmignore
  Dockerfile.e2e
  e2e-verify.sh
  install.sh
  openclaw.plugin.json
  package.json
  SKILL.md
  skills/
    do/
      SKILL.md
    make-plan/
      SKILL.md
  src/
    index.test.ts
    index.ts
  test-e2e.sh
  test-install.sh
  test-sse-consumer.js
  TESTING.md
  tsconfig.json
package.json
plans/
  02-spawn-contract-templating.md
  04-installer-transparency.md
  08-opencode-integration.md
  2026-05-07-server-beta-independent-bullmq-observation-runtime.md
  2026-05-25-cmem-sdk-and-server-rename.md
  2026-06-10-worker-restart-single-source-of-truth.md
  2026-07-03-antigravity-cli-migration.md
  2026-07-05-three-release-branches.md
  2026-07-17-phase5-two-lane-sync.md
  2026-07-22-cmem-launch.md
  inbox/
    2026-07-09-cloud-sync-native.md
  root-cause-holistic-execution.md
plugin/
  .claude-plugin/
    plugin.json
  .codex-plugin/
    plugin.json
  .mcp.json
  bun.lock
  hooks/
    bugfixes-2026-01-10.md
    codex-hooks.json
    hooks.json
  modes/
    code--ar.json
    code--bn.json
    code--chill.json
    code--cs.json
    code--da.json
    code--de.json
    code--el.json
    code--es.json
    code--fi.json
    code--fr.json
    code--he.json
    code--hi.json
    code--hu.json
    code--id.json
    code--it.json
    code--ja.json
    code--ko.json
    code--nl.json
    code--no.json
    code--pl.json
    code--pt-br.json
    code--ro.json
    code--ru.json
    code--sv.json
    code--th.json
    code--tr.json
    code--uk.json
    code--ur.json
    code--vi.json
    code--zh.json
    code.json
    email-investigation.json
    law-study--chill.json
    law-study-CLAUDE.md
    law-study.json
    meme-tokens.json
  package.json
  scripts/
    bun-runner.js
    context-generator.cjs
    mcp-server.cjs
    server-service.cjs
    statusline-counts.js
    transcript-watcher.cjs
    version-check.js
    worker-service.cjs
    worker-wrapper.cjs
  skills/
    babysit/
      SKILL.md
    cloud-sync/
      SKILL.md
    design-is/
      SKILL.md
    do/
      SKILL.md
    how-it-works/
      onboarding-explainer.md
      SKILL.md
    knowledge-agent/
      SKILL.md
    learn-codebase/
      SKILL.md
    make-plan/
      SKILL.md
    mem-search/
      SKILL.md
    oh-my-issues/
      SKILL.md
    pathfinder/
      SKILL.md
    smart-explore/
      SKILL.md
    standup/
      agent-brief.md
      SKILL.md
      standup.mjs
    timeline-report/
      SKILL.md
    version-bump/
      scripts/
        generate_changelog.js
      SKILL.md
    weekly-digests/
      SKILL.md
    what-the/
      SKILL.md
    wowerpoint/
      SKILL.md
  sqlite/
    observations/
      files.js
    SessionStore.js
  ui/
    assets/
      fonts/
        monaspace-radon-var.woff
        monaspace-radon-var.woff2
    claude-mem-logo-for-dark-mode.webp
    claude-mem-logo-stylized.png
    claude-mem-logomark.webp
    icon-thick-completed.svg
    icon-thick-investigated.svg
    icon-thick-learned.svg
    icon-thick-next-steps.svg
    viewer-bundle.js
    viewer.html
ragtime/
  LICENSE
  ragtime.ts
  README.md
README.md
scripts/
  anti-pattern-test/
    detect-error-handling-antipatterns.ts
  bug-report/
    cli.ts
    collector.ts
    index.ts
  build-hooks.js
  build-viewer.js
  build-worker-binary.js
  check-hook-io-discipline.cjs
  check-pending-queue.ts
  check-postinstall-allowlist.js
  check-spawn-env-discipline.cjs
  claude-mem-sync
  clear-pending-queue.ts
  discord-release-notify.js
  e2e-server-docker.sh
  export-memories.ts
  gen-plugin-lockfile.cjs
  generate-changelog.js
  import-memories.ts
  pr-babysit-status.ts
  regenerate-claude-md.ts
  smoke-clean-room.cjs
  strip-comments.ts
... 748 more

claude-mem

Skills

Commands