Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 42 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ share one memory, and no one can read a scope they weren't granted.

## Tools

The server exposes eleven tools: `list_scopes`, `store`, `store_batch`, `search`, `recall`, `find_related`,
The server exposes 11 tools, plus 12 `admin_` tools that only admins see (see [Admins](#admins)): `list_scopes`, `store`, `store_batch`, `search`, `recall`, `find_related`,
`list_recent`, `update`, `delete`, `stats` and `prune`. They match the original server, plus a `scope` argument on the
write tools. Search is hybrid (BM25 full-text plus `gte-small` vector similarity, fused with RRF) with temporal decay.
Delete and prune are soft; rows are purged after 30 days.
Expand All @@ -27,7 +27,7 @@ deno run -A scripts/setup.ts --configure-claude
(your OS user), grants it write access and issues a token. It saves `AGENT_MEMORY_URL`, `AGENT_MEMORY_TOKEN` and
`AGENT_MEMORY_DB_URL` into `.env` (mode 0600; it refuses to write unless git ignores the file) and prints the token once.
`--configure-claude` then runs `claude mcp add` for you. Re-running is safe: nothing is duplicated, and a live token in
`.env` is reused.
`.env` is reused. The member it creates becomes the first admin (see [Admins](#admins)).

Flags: `--env-file <path>` (default `.env`), `--scope <name>` (default `default`), `--member <name>`,
`--email <address>` (optional; only links the member to a Supabase login), `--bot` (a bot member instead of a
Expand Down Expand Up @@ -65,6 +65,10 @@ you pass `--remote` (the linked project, or `--remote=<project-ref>`). `function
The schema `agent_memory` must **not** be listed under Settings, API, Exposed schemas. Access goes only through the
Edge Function; `anon` and `authenticated` have no privileges on it.

Installing by hand, nothing makes you an admin. After creating your own member (see the
[Admin quick-start](#admin-quick-start)), make it the first admin:
`deno run -A scripts/admin.ts set-admin <you> on`.

### Temporal decay

Search scores decay with age, as in the original. The half-life in days is the function secret
Expand Down Expand Up @@ -100,6 +104,38 @@ deno run -A scripts/admin.ts issue-token alice laptop --expires 90d # shown on
Other commands: `list-scopes`, `list-grants`, `list-tokens <member>`, `revoke <member> <scope>` and
`revoke-token <id>`. Tokens look like `amm_…` and only their SHA-256 hash is stored.

### Admins

Some members are admins. An admin can manage the team from Claude, not only from the shell.

- **The first admin** comes from `scripts/setup.ts`: a human member it creates or reuses is made an admin (a `--bot`
member never is). For an existing install, run `deno run -A scripts/admin.ts set-admin <member> on`.
- **Shell-only commands** (they are not available through Claude): `set-admin <member> on|off`,
`reactivate <member>` and `admin-log [--since <ISO|Nd>] [--actor <name>] [--limit N]`.
`delete-scope`, `deactivate` and `list-members` are also shell commands, and admins can do them from Claude too.
Deactivating a member also drops their admin flag, so a reactivated member is not an admin until `set-admin` is run.
A scope can only be deleted once it holds no memories, live or soft-deleted.
- **From Claude**, admins can do the rest with the `admin_` tools: `admin_list_scopes`, `admin_create_scope`,
`admin_delete_scope`, `admin_list_members`, `admin_create_member`, `admin_deactivate_member`, `admin_list_grants`,
`admin_grant`, `admin_revoke`, `admin_issue_token`, `admin_list_tokens` and `admin_revoke_token`.
- **Connecting an onboarded member.** The admin issues a token with `admin_issue_token` (or `issue-token`) and gives it
to the member, who registers it with Claude Code:

```sh
claude mcp add --transport http shared-memory https://<project-ref>.supabase.co/functions/v1/agent-memory \
--header "Authorization: Bearer <token>" -s user
```

or, with the URL and token in an env file (`AGENT_MEMORY_URL`, `AGENT_MEMORY_TOKEN`),
`deno run -A scripts/configure-claude.ts [--name shared-memory] [--scope user]`, as in the Quick start.
- **Handle issued tokens with care.** A token issued through `admin_issue_token` passes through the admin's Claude
transcript, so give it to the member privately (not in a shared channel), and revoke it if it leaks. Do not
auto-allow the `mcp__<server>__admin_*` tools in Claude Code permissions: admin tools run in sessions that also read
memories written by other members, so keep the per-call confirmation on.
- **Admin tools never act on another admin.** Changing an admin, or their grants or tokens, is done from the shell.

Every admin action, from the shell or from Claude, is recorded in the admin log. The log never holds a token.

### Undo, and erasing for good

`delete` and `prune` are soft: a deleted memory stays restorable for 30 days, then the daily job purges it. A purge
Expand Down Expand Up @@ -134,7 +170,8 @@ deno run -A scripts/backup.ts restore-backup backup-<timestamp>.json
`backup` exports the whole install by default; `--scope` limits it to one scope (and the members it references). The
file holds memory content: treat it as private. `restore-backup` loads only into an **empty** install (fresh
migrations, no scopes, members or memories) and keeps ids. Access tokens are never exported, so after a restore,
issue new tokens with `issue-token`.
issue new tokens with `issue-token`. Admin flags and deactivation are kept, and backup files written before admin
support still restore (as non-admin, active members). The admin log is **not** exported, so it starts empty after a restore.

### Import from a local agent-memory-mcp store

Expand Down Expand Up @@ -211,7 +248,8 @@ AGENT_MEMORY_TOKEN=amm_… \
```

It runs every tool once through the real endpoint, then three concurrent searches, prints `PASS` or `FAIL` per tool and
exits non-zero on any failure. It deletes what it stored.
exits non-zero on any failure. It deletes what it stored. An admin token sees the 12 `admin_` tools as well; the smoke
test only checks that they are present, and does not exercise them.

## Development

Expand Down
Loading
Loading