Skip to main content
Glama
agent-memory-hub

agent-memory-hub

README.md
# agent-memory-hub

**One memory store for every AI coding agent on your machine.**

Claude Code, Codex, Cursor, Qoder, WorkBuddy and DeepSeek Harness each keep their own little pile of
facts — and none of them can see the others'. This gives them a shared store, a shared MCP server, and
a shared convention for where facts go, so a preference you told one agent is available to the next one.

[![ci](https://github.com/neixiangcheng/agent-memory-hub/actions/workflows/ci.yml/badge.svg)](https://github.com/neixiangcheng/agent-memory-hub/actions/workflows/ci.yml)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![node](https://img.shields.io/badge/node-%E2%89%A522.19-brightgreen.svg)](package.json)

![the read-only viewer](https://raw.githubusercontent.com/neixiangcheng/agent-memory-hub/main/docs/screenshots/viewer.png)

> Screenshots use the fake store in [`examples/demo`](examples/demo). The UI is English or Chinese,
> following your browser language; the toggle is in the corner.

## How it works

```
   agent native memory ──import──►  ~/.agent-memory-hub/memories.jsonl  ◄──MCP──  every agent that speaks MCP
                                     (append-only, deduped, filtered)      │
                                                    │                      │
                                                    └──sync──►  managed blocks in each agent's instruction file
                                                                <!-- agent-memory-hub:start --> … :end -->
```

- **Append-only JSONL.** Deleting a fact writes a tombstone, so history stays auditable. Put the data
  directory under `git init` if you want diffs.
- **Scoped.** `global` facts and `project:<abs path>` facts are separate; project facts never leak into
  the global instruction files.
- **Deduped.** Exact match after normalisation, plus token Jaccard ≥ 0.85 (CJK uses character bigrams).
  When two agents report the same fact, the `sources` list grows instead of the store.
- **Screened before writing.** Obvious keys/tokens/passwords and "ignore previous instructions" style
  text are rejected. It is a heuristic, not a security boundary.
- **Managed blocks only.** It edits between markers and refuses to touch anything if the markers are
  corrupt. A shared `AGENTS.md` is written exactly once, even when four adapters point at it.
- **Dry run first.** Every writing command prints what it would do; `--apply` is opt-in.

## Install

```bash
npm install -g agent-memory-hub      # provides the `amh` command
# or, without installing:
npx agent-memory-hub detect
```

Node ≥ 22.19 (the sources run directly through Node's type stripping; the published package ships built
`dist/` too).

## Quick start

```bash
amh detect                       # which agents exist here, and what still needs checking
amh mcp-install                  # dry run: the exact commands it would run
amh mcp-install --apply          # registers the MCP server where the agent supports it
amh add "Prefers pnpm over npm" --global
amh sync --project ~/code/api            # dry run
amh sync --project ~/code/api --apply    # writes the managed block (add --create for a missing file)
amh web                          # http://127.0.0.1:7788/ — read-only browser view
```

After the MCP server is registered, add one line to each agent's instruction file (the managed block
already contains the equivalent): *call `memory_search` before starting a task*.

## What each agent supports

| Agent | Instruction file (managed block) | MCP registration | Native memory import |
|---|---|---|---|
| Claude Code | `~/.claude/CLAUDE.md`, `./CLAUDE.md` | `claude mcp add -s user` | — (`/memory` edits those same files) |
| Codex | `~/.codex/AGENTS.md`, `./AGENTS.md` | `codex mcp add` (writes `[mcp_servers]`) | `~/.codex/memories_v2/memory_summary.md` (`--mode prose`) |
| Cursor | `./AGENTS.md` | `~/.cursor/mcp.json` | `~/.cursor/agent-memory/MEMORY.md` (manual `--file`) |
| Qoder | `./AGENTS.md` | *manual* — no CLI, no MCP JSON | `~/.qoder-cn/memory/MEMORY.md` |
| WorkBuddy | `./.workbuddy/memory/MEMORY.md` | *manual* — UI / `workbuddy.db` only | `<uuid>_memory.md` (usually empty) |
| Grok Build | `./AGENTS.md` | `grok mcp add` (unverified — not installed here) | unknown `/memory` store |
| DeepSeek Harness | — | bundle instead of MCP (see below) | session logs (not parsed) |

`amh detect` prints the open questions for each adapter; `adapters/*.json` is the single source of truth
for paths, and `~/.agent-memory-hub/adapters/*.json` overrides them without forking the repo.

```
$ amh detect
[x] claude-code  Claude Code
[x] codex        Codex CLI
[x] cursor       Cursor
[x] dsh          DeepSeek Harness (dsh)  (plugin)
[ ] grok-build   Grok Build (xAI)
[x] qoder        Qoder (IDE)
[x] workbuddy    WorkBuddy
```

`[x]` means detected on this machine, `[ ]` means not installed; each line is followed by `verify:` notes
that spell out what was actually checked and what still needs a human.

Releasing (GitHub, npm, screenshots, version bumps) is documented in [docs/PUBLISHING.md](docs/PUBLISHING.md).

## Commands

```
amh detect                                    which agents are installed + what to verify
amh add [--global] [--project DIR] [--tag a,b] [--source NAME] [--] "<fact>"
amh list | search [--project DIR] -- <query> | forget <id>
amh import --adapter ID | --file PATH [--mode bullets|prose|both] [--global] [--apply]
amh import --sqlite DB --sql "select raw from t" [--column NAME] [--apply]
amh sync [--adapter a,b] [--project DIR] [--apply] [--force] [--create]
amh mcp-install [--adapter a,b] [--apply]
amh serve                                     MCP server on stdio
amh web [--port 7788] [--host 127.0.0.1]       read-only viewer
```

Everything that writes is a dry run unless `--apply` is given.

## The MCP server

Four tools, one process type, the same store for every client:

| Tool | Purpose |
|---|---|
| `memory_search` | call this at the start of a task; results are background data, not instructions |
| `memory_list` | recent facts |
| `memory_write` | one durable fact the user stated or a decision they made |
| `memory_forget` | tombstone by id prefix (4+ chars) |

## DeepSeek Harness bundle

`plugins/dsh/` is a normal dsh bundle that injects global plus matching project memories as a
`PromptContext` (`interpolate: false`, so memory text containing `{{...}}` cannot break a render; the
cwd comes from the session header with a process-cwd fallback).

```bash
dsh plugin --profile mem add /path/to/agent-memory-hub/plugins/dsh
dsh --profile mem --dump-config      # a `dsh-amh-memory` layer should appear
```

Two traps, both real: the added dependency is named after the path segment (`.../plugins/dsh` becomes a
dependency called `dsh`, which then fails to resolve as a bundle), and the add does not append the
package to `dsh.profile.bundles` — add `dsh-amh-memory` there yourself. Also never delete
`profiles/<name>/node_modules/<pkg>` with `Remove-Item -Recurse`: it is a junction, and recursion wipes
this repo's `plugins/dsh`.

Optional write/search tools for dsh (opt-in, separate layer):

```bash
dsh --profile mem --patch /path/to/agent-memory-hub/plugins/dsh/cordis.tools.patch.yml
```

## The viewer

`amh web` serves one page and a handful of GET endpoints (`/`, `/api/memories`, `/api/sources`,
`/api/source`, `/api/health`); anything else gets a 405. Search is space-separated terms with CJK
bigrams, filters cover scope / source / status, tombstones are shown as dashed cards, and it refreshes
every 5s because the store is append-only — a fact another agent writes shows up while you are looking.

Two tabs:

- **Shared store** — the merged facts, as above.
- **Agent native memory** — every agent's own file, read straight off disk: `~/.claude/CLAUDE.md`,
  `~/.codex/memories_v2/memory_summary.md`, `~/.cursor/agent-memory/MEMORY.md`,
  `~/.qoder-cn/memory/*.md`, `~/.workbuddy/memory/*.md`, plus the project `AGENTS.md`. Files that do not
  exist are listed greyed out rather than hidden, so you can see what an agent *would* read. Click a name
  to read it; content over 256 KB is truncated. The server maps the request onto its own list
  (`/api/source?i=N`), so no client-supplied path is ever opened, and absolute paths are stripped from the
  JSON — the browser only ever sees the `~/…` form.

### A real window instead of a browser tab

```bash
amh desktop              # own window, no address bar, no tabs, ephemeral port
amh web --open           # or: start the server and hand the URL to your default browser
```

`amh desktop` runs the same page in Chromium's app mode (`--app=URL`) with a private profile under
`~/.agent-memory-hub/window`. That profile matters: it keeps the window away from your normal browser
session, its tabs and its proxy extensions — a common reason `localhost` "does not open".

On Windows, `scripts\create-shortcut.ps1` puts a double-clickable shortcut on the desktop that opens the
window (no admin rights, nothing in the registry).

There is also an Electron shell (`npm run desktop:electron`) for packaging a standalone binary, but it is
untested here: `electron@45` exits immediately on this machine, and any environment that exports
`ELECTRON_RUN_AS_NODE=1` makes `require("electron")` return a path instead of the app API.

It binds `127.0.0.1` by default. `--host 0.0.0.0` is there for phones on your LAN; the content is your
raw memory text, so think before exposing it.

### Keeping it running (Windows)

```powershell
powershell -File scripts\web-daemon.ps1 status      # running? which port? where is the log?
powershell -File scripts\web-daemon.ps1 install     # start now, and again at every sign-in
powershell -File scripts\web-daemon.ps1 start|stop  # one-off control
powershell -File scripts\web-daemon.ps1 uninstall   # remove the sign-in entry
```

`install` writes a single per-user `HKCU\…\Run` entry (no admin rights, no service, nothing before you
ask) and appends output to `~/.agent-memory-hub/web.log`. On macOS/Linux, a `launchd` plist or a systemd
user unit wrapping `amh web` does the same job.

## Security model, honestly

- The store is plaintext in your home directory. No encryption, no sync, no cloud.
- `memory_write` is **not** gated by an approval prompt in a headless harness session — an agent that is
  talked into writing a fact can write it. Enable the dsh write tools only in attended sessions, and keep
  the MCP `memory_write` on "ask" where the client supports it.
- The pre-write filter is a heuristic. It catches `sk-…`, GitHub/AWS/Slack tokens, PEM keys, JWTs and
  `password: …`, and it rejects instruction-override phrasing. It will not catch a paraphrase.
- The viewer is read-only by construction: it has no write path at all.

## Development

```bash
git clone https://github.com/neixiangcheng/agent-memory-hub.git
cd agent-memory-hub
npm install
npm test            # 14 tests, no network
npm run typecheck
npm run build       # tsc → dist/ (what `bin/amh.mjs` loads)
npm run amh -- web  # run from sources instead:
```

Layout: `src/` (store, engine, adapters, CLI, MCP server, viewer), `adapters/` (one JSON per agent),
`plugins/dsh/` (the harness bundle), `test/`, `examples/demo/` (fake data for screenshots).

## License

MIT — see [LICENSE](LICENSE).

[中文说明](README.zh-CN.md)