diff --git a/CLAUDE.md b/CLAUDE.md index 9fbf9b5..6de8220 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 diff --git a/README.md b/README.md index 14cbec7..a2394dc 100644 --- a/README.md +++ b/README.md @@ -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 # soft delete, recoverable for 30 days +deno run -A scripts/admin.ts restore-thread +deno run -A scripts/admin.ts erase-thread # shows scope and title, exits 1 +deno run -A scripts/admin.ts erase-thread --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. @@ -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-.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 @@ -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. @@ -247,9 +284,11 @@ AGENT_MEMORY_TOKEN=amm_… \ deno run -A scripts/smoke.ts --scope ``` -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 diff --git a/docs/claude-md-sample.md b/docs/claude-md-sample.md new file mode 100644 index 0000000..8094138 --- /dev/null +++ b/docs/claude-md-sample.md @@ -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 | +|-------|------------| +| `` | | +| `` | | + +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:`, always; +- exactly one of `status:open`, `status:in-review`, `status:blocked` or `status:done`; +- `pr:` / `issue:` 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:` 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 `-`, 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. diff --git a/docs/superpowers/plans/2026-11-07-threads.md b/docs/superpowers/plans/2026-11-07-threads.md new file mode 100644 index 0000000..145c118 --- /dev/null +++ b/docs/superpowers/plans/2026-11-07-threads.md @@ -0,0 +1,578 @@ +# Discussion Threads Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or +> superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Scoped, append-only discussion threads linked to memories. Agent-held sessions subscribe to threads and +poll `whats_new`, and memory and thread writes record the session. + +**Architecture:** One new migration holds the tables, the RLS select policies and every write as a SECURITY DEFINER +function, so the rules live in Postgres as they do today. A new `PgThreadStore` (`_shared/thread-store.ts`) runs +through `withMember` and calls those functions. Reads go through RLS-protected views. A new +`_shared/thread-tools.ts` registers 11 tools for every member, plus `admin_delete_thread` for admins. `recall` +attaches linked threads, and memory writes accept a session. + +**Tech Stack:** as the existing project: Postgres 17 migrations + pgTAP, Deno, `npm:postgres@3.4.5`, +`npm:@modelcontextprotocol/server@2.4.0`, `npm:zod@4.6.7`. + +**Spec:** [docs/superpowers/specs/2026-11-07-threads-design.md](../specs/2026-11-07-threads-design.md). Read §3 and §4 +before any task: the session and marker rules there are binding. + +## Global Constraints + +- **All schema work goes in ONE NEW migration, `supabase/migrations/20261107180000_threads.sql`.** Tasks 1–3 append to + it. No earlier migration changes, and `supabase db reset` must build from empty. Replacing an existing function or + view uses `create or replace` (or `alter policy`) inside the new file. +- **Every function** is `security definer`, `set search_path = ''`, with fully qualified names, then + `revoke execute … from public`. Member-callable functions are then granted to `agent_memory_member`. `adm_*`, purge, + erase and restore stay postgres-only. +- **Members get `select` only on the new tables and views.** They get no insert, update or delete grants. Every write + goes through a function. +- **User-safe errors are `raise exception ''`** (SQLSTATE P0001). The TS layer turns P0001 into `StoreError(message)`, + exactly as `PgAdminStore.run` does, and anything else into `Database error`. +- **Exact error texts:** + - `Thread not found` + - `Memory not found` + - `Session not found` + - `Scope '' not found` + - `No write access to scope ''` + - `Title must be 1-200 characters` + - `Post body is empty` + - `content too long (max 20000 characters)` + - `Thread is already resolved` + - `Thread is already open` + - `Session label '