Skip to content

Hosted shared agent memory on Supabase - #1

Merged
springfall2008 merged 37 commits into
mainfrom
feat/hosted-memory
Nov 7, 2026
Merged

springfall2008 merged 37 commits into
mainfrom
feat/hosted-memory

Conversation

@springfall2008

Copy link
Copy Markdown
Owner

What this is

A hosted MCP memory server on Supabase, built from the design and plan. It keeps agent-memory-mcp's tools and adds scopes: named memory pools, with read-only or read-write access per member. Postgres row-level security enforces that access.

Clients connect with a URL and a personal amm_ token. Nothing is installed locally.

What's in it

  • Database (supabase/migrations/, schema agent_memory):
    • scopes, members, grants, memories, history and hashed tokens;
    • an RLS policy on every table, keyed on the member id;
    • member writes limited to specific columns, so a member can't forge authorship or backdate a deletion;
    • soft delete with a 30-day purge (pg_cron) that also scrubs content from history, plus an admin erase;
    • hybrid search in SQL: full-text ranking plus exact pgvector cosine distance, merged with RRF (k = 60).
  • Edge Function agent-memory:
    • turns a bearer token into a member, then runs every query as role agent_memory_member, so RLS applies;
    • stateless MCP (@modelcontextprotocol/server 2.4.0) with 11 tools: the original 10 plus list_scopes;
    • temporal decay ported unchanged from the original;
    • gte-small embeddings.
  • Scripts:
    • setup.ts takes an empty project to a working token saved in .env; configure-claude.ts registers the server with Claude Code at user scope;
    • admin.ts manages scopes, members, grants and tokens, and has list-deleted, restore and erase;
    • backup.ts, import.ts (with lancedb-export/) and smoke.ts.
  • CI: lint, type-check, unit tests, pgTAP RLS tests and integration tests against the local Supabase stack.

Design decisions worth a look

  • Exact similarity search, no ANN index.
    • An HNSW index filtered by RLS afterwards gave short result pages. A member who could read 15 of 1,000 rows got 1 result instead of 10.
    • The number of results also hinted at hidden rows near the query.
    • An exact scan takes milliseconds at the expected size. Revisit at around 50k memories.
  • CPU limits from the free-tier spike (results).
    • CPU time is counted per worker, not per request, so each request should stay under about 1 s.
    • So store_batch takes at most 2 memories, and recall embeds at most 5 topics; further topics are searched by keyword only.
  • Admin scripts use a direct DB connection (AGENT_MEMORY_DB_URL), not the service-role key. The agent_memory schema is deliberately not exposed through the Data API.
  • Prune with decay disabled (MEMORY_DECAY_HALF_LIFE ≤ 0) flags only memories never accessed and older than 90 days. This deliberately differs from the original, so that turning decay off can't make prune delete everything.

Testing

  • pgTAP: 141 tests, covering RLS as read-only, read-write and ungranted members, impersonation attempts, the SECURITY DEFINER functions and search.
  • Unit: 62 tests. Integration against the local stack: 56 tests.
  • End-to-end over real MCP against supabase functions serve, run locally. It isn't in CI because it needs the edge runtime and the model download.
  • Deployed to a free Supabase project, where the smoke test passed every tool plus a concurrent burst.

Not yet verified: CI on GitHub. This PR is its first run.

Credits

Builds on agent-memory-mcp by Adam Drew, via the chalfontchubby fork. GPL-3.0-or-later.

🤖 Generated with Claude Code

springfall2008 and others added 30 commits November 7, 2026 11:21
Single gte-small embed fits the free tier (~92 ms short, ~305 ms typical,
~455 ms at the 512-token cap). CPU is accounted per worker, so budget
~1 s per request: store_batch cap 2, recall topic cap 5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Thirteen TDD tasks: schema, RLS, SQL functions and search (pgTAP), shared
core and decay port, Postgres store, MCP tools, admin CLI, Edge Function,
backup, LanceDB import, then CI/README/deploy/smoke. Caps from the spike.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…om empty

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Also type-check every TS file (the old glob did not recurse), add the
hosted smoke test, and capture the expected server-side error log in the
pg-store-write test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Every result limit (search, find_related, list_recent, recall) must be
  an integer in 1..100; otherwise StoreError('limit must be between 1
  and 100').
- One content cap, MAX_CONTENT_CHARS = 20000, shared by store,
  store_batch, update (checked before embedding), /embed and import.
- recall validates limit_per_topic and include_recent before embedding,
  and include_recent <= 0 returns recent: [] as the original does.
- store_batch's description states the 2-per-call cap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With MEMORY_DECAY_HALF_LIFE <= 0 nothing decays, so "strength 0 <
minStrength" no longer makes every memory a candidate. Only the dormant
rule applies (never accessed and older than maxDormantDays). stats and
prune still share the one verdict. A deliberate deviation from the
original, noted in the code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
springfall2008 and others added 7 commits November 7, 2026 13:05
New migration (earlier ones are pushed and stay as they are):
- the history trigger's 'purge' row records only memory, action,
  member, time and previous scope;
- purge_tombstones() also nulls prev_content, prev_category and
  prev_tags on every earlier history row of each purged memory;
- agent_memory.erase(id): postgres-only, hard-deletes a live or
  soft-deleted memory now, with the same scrub; returns whether a row
  existed;
- memories purged before this migration are scrubbed once.

pgTAP 05_erase covers purge, erase (live and soft-deleted), the kept
trail, a targeted scrub and the member privilege check (42501).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- erase <memory-id> --yes hard-deletes now; without --yes it prints the
  id, scope and first line and exits 1.
- list-deleted [--scope] [--by member|admin] [--since ISO] shows
  soft-deleted memories with who deleted them (latest 'delete' history
  row) and the first line, up to 80 characters.
- restore takes several ids, or the same filters with --yes (without
  --yes it lists what it would restore and exits 1), in one
  transaction, and prints how many it restored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README's commands use CLI 3 flags (db push --remote, functions
deploy --remote=<ref>), so CI runs the same version as development.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Require Supabase CLI 3.x; fix the deploy line (CLI 3 uses the linked
  project or --remote=<ref>, not --project-ref).
- MEMORY_DECAY_HALF_LIFE: default 30, <= 0 disables decay, and prune
  then applies only the dormant rule.
- list-deleted, multi and filtered restore, erase.
- backup covers the whole install unless --scope; restore-backup needs
  an empty install and does not restore tokens.
- The import workflow end to end, with its environment variables.
- Percent-encode special characters in the admin connection password.
- Size limits; drop a stray blank line under Credits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@springfall2008
springfall2008 merged commit 3057d21 into main Nov 7, 2026
1 check passed
@springfall2008
springfall2008 deleted the feat/hosted-memory branch November 7, 2026 13:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant