mem

<!-- markdownlint-disable MD013 MD033 MD041 --> <div align="center"> <img src="web/public/favicon.svg" width="72" alt="mem logo"> <h1>mem</h1> <p><strong>Your agents change. Their memory should not.</strong></p> <p><strong>Agent 会更换，记忆不该重来。</strong></p> <p>A portable, self-hosted memory plane for AI agents, with one core across API, MCP, CLI, and Web.</p> <p>面向 AI Agent 的可迁移、自托管记忆平面；API、MCP、CLI 与 Web 共用同一内核。</p> <p> <a href="https://github.com/bytefolk/mem/actions/workflows/ci.yml"><img src="https://github.com/bytefolk/mem/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="Apache 2.0 license"></a> <a href="https://github.com/bytefolk/mem/releases"><img src="https://img.shields.io/github/v/release/bytefolk/mem?display_name=tag&sort=semver" alt="Latest release"></a> <a href="docs/mcp.md"><img src="https://img.shields.io/badge/MCP-26_tools-5A67D8" alt="26 MCP tools"></a> <a href="https://smithery.ai/server/@bytefolk/mem-mcp"><img src="https://smithery.ai/badge/@bytefolk/mem-mcp" alt="Smithery"></a> </p> <p> <a href="#quickstart">Quickstart</a> · <a href="#connect-an-agent-over-mcp">MCP setup</a> · <a href="docs/DEPLOYMENT.md">Deployment</a> · <a href="SPEC.md">Specification</a> · <a href="docs/DEVELOPMENT.md">Contributing</a> </p> </div> <!-- markdownlint-enable MD013 MD033 MD041 --> <!-- markdownlint-disable MD013 -->

mem gives agents a durable place to write decisions, evidence, task state, and files, then recall them in a later session or from another agent. You keep the data and choose where it runs. mem does not run the agent or generate its answer.

mem 为 Agent 提供一块由用户掌控的长期记忆空间：保存决定、证据、任务状态和原始文件，并让另一段会话、另一个 Agent 或另一台设备继续使用。数据由你持有，部署位置由你决定；mem 不负责运行 Agent，也不替 Agent 生成答案。

Use it when you need to:

• hand work from Claude Code to Codex, another host, or another machine;
• resume a task from an immutable checkpoint instead of reconstructing chat history;
• recall a decision together with its source and scope;
• keep files and structured memory behind the same authorization boundary;
• export a workspace and restore it into another mem deployment.

[!WARNING] mem is in active experimental development. Interfaces, storage schemas, and release artifacts can change. Do not use it as the only copy of important data. The current deployment profiles are for private self-hosting, not an Internet-facing multi-tenant service.

How it works

flowchart LR
    A["Claude Code / Codex / Cursor / your agent"] -->|MCP| M["mem-mcp"]
    C["Scripts and operators"] -->|CLI / HTTP| API["memd"]
    U["People"] -->|Web| W["Web app"]
    M --> API
    W --> API
    API --> P[("PostgreSQL + pgvector")]
    API --> O[("S3-compatible objects")]
    API --> Q["Redis / indexing worker"]
    API --> R["Evidence-backed recall"]

The HTTP service owns the canonical behavior. MCP, CLI, and Web call the same API instead of maintaining separate memory models.

A typical agent loop looks like this:

1. remember a sourced observation, decision, preference, task state, or artifact reference.
2. checkpoint work under a stable task key before switching sessions or agents.
3. context or resume later to retrieve bounded, evidence-backed state.
4. Record feedback, archive stale memory, or explicitly forget content when policy allows it.

Model-independent structured memory and lexical recall work without an LLM or embedding provider. Optional indexing can add embeddings and extraction, but it is not a hidden dependency for remember, lifecycle control, checkpoint, or deterministic resume.

Quickstart

The supported first-run path uses Docker Compose. It starts the Web app, memd, the Worker, PostgreSQL, Redis, and MinIO on one machine.

Requirements: Docker Engine and Docker Compose v2.

git clone https://github.com/bytefolk/mem.git
cd mem/deploy/compose

./generate-env.sh
chmod 600 .env
docker compose --env-file .env -f compose.yaml up -d --build --wait
curl --fail http://127.0.0.1:8080/healthz

Open http://localhost:8080 and register the first user. The default first_user mode accepts one account, then disables registration.

For the CLI, build from source and sign in:

cd ../..
make build-mem
export PATH="$PWD/bin:$PATH"
export MEM_SERVER=http://localhost:8080

mem auth login
mem doctor

Now write and recall model-independent memory:

mem remember "Review auto-renewal before signing" \
  --kind decision \
  --path /Contracts \
  --idempotency-key contract-renewal-v1 \
  --agent-id claude-code

mem context "What should I check before signing?" \
  --source memory \
  --scope /Contracts

The detailed deployment guide covers TLS, secrets, backups, upgrades, production invariants, Helm, and the exact first-user/token flow: docs/DEPLOYMENT.md.

Connect an agent over MCP

mem-mcp is a stdio MCP adapter for the canonical memd API. Build it from the same revision as the server, then configure your host with the resulting executable:

make build-mem-mcp

{
  "mcpServers": {
    "mem": {
      "command": "/absolute/path/to/mem/bin/mem-mcp",
      "env": {
        "MEM_SERVER": "http://localhost:8080",
        "MEM_TOKEN": "mem_..."
      }
    }
  }
}

Claude Code users can register the same executable from the command line:

claude mcp add --scope project --transport stdio \
  --env MEM_SERVER=http://localhost:8080 \
  --env MEM_TOKEN=mem_... \
  mem -- /absolute/path/to/mem/bin/mem-mcp

The ByteFolk npm wrapper is not yet a supported installation path. Its release migration is tracked in issue #153.

The adapter currently exposes 26 tools. The main groups are:

| Need | MCP tools | | --- | --- | | Store and inspect files | mem_put, mem_get, mem_info, mem_list, mem_ls | | Write and recall memory | mem_remember, mem_search, mem_context, mem_related | | Resume work | mem_checkpoint, mem_task_list, mem_checkpoint_list, mem_checkpoint_get, mem_resume | | Control lifecycle | mem_feedback, mem_archive, mem_restore, mem_forget | | Manage file organization | mem_mkdir, mem_mv, mem_folder_tree |

See docs/mcp.md for every tool, permission requirement, response limit, and host-specific setup.

What ships today

| Capability | Current behavior | | --- | --- | | Structured memory | Idempotent writes for observations, decisions, preferences, task state, facts, notes, and artifact references, with source and producer provenance | | Recall | Lexical structured-memory recall; file lexical/vector routes where the selected profile and index support them; bounded context packs with evidence and explicit partial-result warnings | | Task continuity | Versioned immutable checkpoints, handoff payloads, task history, and deterministic resume | | Files | Upload, download, folders, metadata, annotations, search surfaces, and scoped access | | Memory lifecycle | Feedback, pin/unpin, archive, restore, and permissioned irreversible redaction after confirmation | | Portability | Validated workspace export and conflict-safe fresh import | | Interfaces | HTTP API, Go CLI, 26-tool MCP server, and React Web application over one service contract | | Deployment | Private single-node Compose and a Helm profile that expects external PostgreSQL, Redis, and S3-compatible storage |

The specification is the source of truth for API semantics. The changelog records what landed in each release.

Trust boundaries

Memory is useful only when callers can tell what it is, where it came from, and who may read it. mem therefore keeps these rules in the core service:

• Tokens are workspace-bound and can restrict scopes and virtual paths.
• Structured memory carries source and producer provenance.
• Writes support idempotency keys; conflicting replay fails instead of silently changing history.
• Recall reports partial results and warnings when one source degrades.
• Checkpoints are immutable; resuming an older checkpoint does not rewrite the task history.
• Workspace import fails on conflict in the current fresh mode rather than merging or overwriting silently.
• Model stages are explicit. A profile does not silently fall back to another provider.
• Production examples keep PostgreSQL, Redis, object storage, memd, and the Worker on private networks.

Read SECURITY.md before exposing a deployment, and use a private security advisory for vulnerabilities.

What mem is not

• An agent runtime. Your agent still owns planning, tool use, reasoning, and final answers.
• A chat product. The Web app is a file and memory control surface, not an assistant persona.
• A hosted public SaaS you can expose without additional work. Current deployment profiles target private environments.
• A claim that every modality or retrieval route is production-ready. Profiles advertise supported stages, and unsupported routes fail closed.
• A bidirectional sync drive. mem put --watch is a one-way foreground watcher for new local files.

Current gaps and sequencing are documented in GOAL.md and docs/AGENT_MEMORY_DIRECTION.md. In particular, conservative merge restore, automatic consolidation and correction/supersede relationships, and fully evaluated versioned ranking remain follow-up work.

Choose your surface

| Surface | Best for | Start here | | --- | --- | --- | | MCP | Agents that need memory tools inside an existing host | MCP guide | | CLI | Imports, scripts, checkpoints, workspace transfer, and operations | make build-mem, then mem --help | | HTTP API | Applications that need the canonical contract directly | SPEC.md | | Web | Browsing files, reviewing memory, lifecycle controls, and workspace transfer | Compose quickstart |

Deployment options

| Profile | Shape | Intended use | | --- | --- | --- | | Single-node Compose | Web, memd, Worker, PostgreSQL, Redis, and MinIO on one Linux host | Personal, team, edge, and evaluation installations | | Multi-node Helm | Replicated Web and Worker, one memd, external stateful services | Private platforms that operate PostgreSQL, Redis, and S3 separately | | Bare-metal development | Local processes and data under .dev/ | Contributors changing Go, Python, or Web code |

Use docs/DEPLOYMENT.md for private deployment and docs/RUN_LOCAL.md only for source development.

Repository map

mem/
├── server/          Go HTTP service, CLI, and MCP server
├── worker/          Python extraction and embedding worker
├── web/             React/Vite control surface
├── deploy/          Compose and Helm deployment assets
├── benchmarks/      Offline recall fixtures and gates
├── docs/            Architecture, operations, acceptance, and integration docs
├── GOAL.md          Product direction and migration boundary
└── SPEC.md          Canonical product and interface contract

Develop and verify

Development requires Go 1.25, Python 3.11+ with uv, Node.js 24, Docker Compose, and the pinned protobuf toolchain when protobuf definitions change.

make bootstrap
make test
make lint
make build

Storage, authorization, migration, memory, handoff, and workspace-transfer changes also require the PostgreSQL integration and process-level acceptance suites. Use docs/TESTING.md for exact commands and disposable-database requirements.

Contributing

This repository uses an issue-first, pull-request-only workflow. A material change needs a ready issue with acceptance criteria before implementation. Every PR must link its tracking record, include a reproducible validation ledger, pass req