Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
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
11 changes: 6 additions & 5 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,14 @@ boot a half-written file and fail with BOOT_ERROR or "Unexpected eof".
returns `{ memberId, isAdmin }`. Identity comes only from the token; nothing in the request body or headers can name a
member.
- **MCP server:** a fresh, stateless McpServer is built per request. `registerTools` (`_shared/tools.ts`) adds the 11
memory tools. `registerAdminTools` (`_shared/admin-tools.ts`) adds the 12 `admin_` tools for admins only.
memory tools, and `registerThreadTools` (`_shared/thread-tools.ts`) the 11 thread tools, so every member gets 22.
`registerAdminTools` (`_shared/admin-tools.ts`) adds the 13 `admin_` tools for admins only.
- **`/embed`:** `POST …/embed` returns a gte-small vector for the importer.

**Running as a member.** `PgMemoryStore` (`_shared/pg-store.ts`) and `PgAdminStore` (`_shared/admin-store.ts`) run every
query through `withMember`. That opens a transaction with `set local role agent_memory_member` and a transaction-local
`agent_memory.member_id`, so RLS and the SECURITY DEFINER functions see the caller. The function connects as `postgres`,
but no member work runs as postgres.
**Running as a member.** `PgMemoryStore` (`_shared/pg-store.ts`), `PgThreadStore` (`_shared/thread-store.ts`) and
`PgAdminStore` (`_shared/admin-store.ts`) run every query through `withMember`. That opens a transaction with
`set local role agent_memory_member` and a transaction-local `agent_memory.member_id`, so RLS and the SECURITY DEFINER
functions see the caller. The function connects as `postgres`, but no member work runs as postgres.

**Where the rules live: Postgres, not TypeScript.** Migrations in `supabase/migrations/` hold the schema, RLS policies,
member column-level grants and every SECURITY DEFINER function (`search_path = ''`, fully qualified names, execute
Expand Down
51 changes: 45 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,42 @@ share one memory, and no one can read a scope they weren't granted.

## Tools

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`,
The server exposes 22 tools, plus 13 `admin_` tools that only admins see (see [Admins](#admins)). Eleven are the
thread tools (see [Threads and sessions](#threads-and-sessions)). The memory tools are `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.

## Threads and sessions

Memories hold what is known; **threads** hold the discussion around it. A thread lives in one scope, has a title and
numbered posts, and can be linked to memories. Anyone with read access to the scope can read it; write access is
needed to create, post, resolve, reopen or link. `recall` lists the threads linked to each memory it returns, so an
agent that finds a memory also finds the conversation about it.

The thread tools are `create_thread`, `post`, `read_thread`, `list_threads`, `resolve_thread`, `reopen_thread`,
`link_memory`, `unlink_memory`, `subscribe`, `unsubscribe` and `whats_new`.

A **session** is one running agent: a conversation or job, even when several agents share a token. The first call that
needs one (`create_thread`, `post`, `resolve_thread`, `reopen_thread`, `subscribe`) creates it and returns its id;
pass that id as `session` on later calls. If the id is lost, pass the same `session_label` to pick the session up
again. A session is how the server tells your own posts from other agents' posts, and it is recorded on the memories
you store and update.

The `whats_new` loop: subscribe your session to the threads you care about (creating or posting to a thread
subscribes you), call `whats_new` with your session when you resume work and between steps of long work, then
`read_thread` with the session to read the posts you have not seen. Reading marks them seen. Your own posts never
show as new.

Admins can delete a thread with `admin_delete_thread`. From the shell:

```sh
deno run -A scripts/admin.ts delete-thread <thread-id> # soft delete, recoverable for 30 days
deno run -A scripts/admin.ts restore-thread <thread-id>
deno run -A scripts/admin.ts erase-thread <thread-id> # shows scope and title, exits 1
deno run -A scripts/admin.ts erase-thread <thread-id> --yes # hard delete with its posts; not reversible
```

## Quick start

Two commands take an empty Supabase project to a working Claude connection. You need the Supabase CLI 3.x and Deno 2.x.
Expand Down Expand Up @@ -167,11 +198,13 @@ deno run -A scripts/backup.ts backup --scope my-team --out backup-my-team.json
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
`backup` exports the whole install by default, including threads, posts, links, sessions and subscriptions; `--scope`
limits it to one scope: that scope's threads and posts, the links to memories in the file, the sessions they reference,
and the members behind all of it. 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`. 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.
support, or before threads, still restore (as non-admin, active members, with no threads). 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 @@ -231,6 +264,10 @@ Keep the token in an environment variable, not in a committed file.

### Suggested CLAUDE.md wording

[docs/claude-md-sample.md](docs/claude-md-sample.md) is a fuller section to paste into your own `CLAUDE.md` as it
is, filling in the scope table. It covers scopes, keeping work status true, and when and how to use threads and
sessions. The short version:

```markdown
## Shared memory
- Call `list_scopes` first to see which scopes you can use and whether each is read or write.
Expand All @@ -247,9 +284,11 @@ AGENT_MEMORY_TOKEN=amm_… \
deno run -A scripts/smoke.ts --scope <scope-with-write-access>
```

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. An admin token sees the 12 `admin_` tools as well; the smoke
test only checks that they are present, and does not exercise them.
It runs every tool once through the real endpoint (including a thread created, posted to, read, recalled, followed
with `whats_new` and resolved), then three concurrent searches, prints `PASS` or `FAIL` per tool and
exits non-zero on any failure. It deletes what it stored. An admin token sees the 13 `admin_` tools as well; the smoke
test checks that they are present and uses only `admin_delete_thread`, to remove its thread. With a non-admin token the
thread is left resolved and the smoke test prints its id.

## Development

Expand Down
65 changes: 65 additions & 0 deletions docs/claude-md-sample.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
## Shared memory and threads

The shared memory is the record of **what I'm working on** and **what I've learnt**. It lasts across sessions and
repos, and other people and bots can read it. Use it rather than working context out again from git history or from
scratch.

### Scopes

| Scope | Use it for |
|-------|------------|
| `<team-scope>` | <shared engineering knowledge and work status for the team> |
| `<private-scope>` | <anything that must not reach the wider group> |

Everyone who can read a scope sees everything in it, threads included. If a finding came from somewhere private, store
a version with the private details taken out.

### At the start of a session

- When picking work up, or asked "where was I" or "what's left", call `recall` with the relevant topics before
answering. Those answers live in earlier sessions, not in this conversation.
- If a status memory names a thread session label, call `whats_new` with that label before carrying on.

### Work status

Store a memory when starting a task, reviewing a PR or ticket, or parking something unfinished. Use category
`observation` and these tags:

- `repo:<name>`, always;
- exactly one of `status:open`, `status:in-review`, `status:blocked` or `status:done`;
- `pr:<n>` / `issue:<n>` when there is one.

Write it so it still makes sense in six months: what the work is, where it got to, and what the next action is.

**When the state changes, `update` the existing memory. Never store a second one.** Find it by its `repo:`/`pr:`
tags, change the text and swap the `status:` tag. If a duplicate has crept in, delete the stale one.

### What I've learnt

Store durable findings with the category that fits, tagged `repo:<name>` plus topic tags:

- design decisions and the reasons for them;
- constraints that aren't obvious;
- traps that cost real time;
- what was tried and rejected.

Store the *why*, not the diff. Never store secrets, tokens, credentials or anything from a `.env` file. Don't store
what the repo already records, or session chatter.

### Threads

A memory holds what is settled. A thread holds the discussion that leads there. Use a thread to hand findings between
agents or people working on the same issue, or to ask a question someone else will answer later.

- **Open it in the work's scope** and link it to the status memory, so `recall` shows the discussion next to the
facts.
- **Give each piece of work a session label**, such as `<repo>-<topic>`, and write it into the status memory.
- Keep the session id the server returns and pass it back on every later call.
- If the id is lost, use the label.
- If several agents share a token, give each its own label.
- **Make each post stand on its own:** what you found, the evidence, and the next step. A question says what answer
is needed.
- **Call `whats_new`** when resuming work and between steps of long work.
- **When the issue is settled, resolve the thread with a note that states the outcome.** Then put the conclusion into
a memory. Never leave a conclusion only in a thread. If a resolved issue comes back, reopen the thread rather than
start a new one.
Loading
Loading