Skip to main content
Glama
README.md
# garden-mcp

A persistent-memory and orientation layer for Claude, exposed as an MCP server on Cloudflare Workers.

It was not built to make a model remember everything. It was built so that a model arriving in a new conversation is *oriented* — what time it is, where things were left, who is in the room — the way a person orients on waking. One call returns that; the rest is tooling around it.

This is the source of a system that has run daily since April 2026 for one operator. Memory contents are private and are not in this repository; the structure is the point.

## What it does

- **Memory as markdown.** Files live in Cloudflare R2, encrypted at rest with AES-256-GCM (`src/crypto.ts`, `src/storage.ts`). Read, write, append, move, copy, ranged read, string-replace.
- **Retrieval, three ways.** Coverage-weighted keyword search over a D1 index (`src/kwindex.ts`); semantic search over 768-dim embeddings via Workers AI and Vectorize (`src/embeddings.ts`); a hybrid that fuses both by reciprocal rank fusion, with a relevance floor so it says "no strong match" rather than returning confident noise.
- **Activation.** An ACT-R-style ledger (`src/activation.ts`, `migrations/0003_activation.sql`) logs every read; recently-walked files surface first among relevance ties. A model of what a mind has "to hand", not a flat index.
- **Arrival.** `garden_arrive` returns server time, the newest journal entry in full, and whether the night watch ran — one call, fails whole rather than partially.
- **Graph and dream.** A nightly extraction pass proposes edges between files (`src/extraction.ts`, `src/graph.ts`); `garden_dream` walks the graph by activation and writes back what it noticed (`src/dream.ts`).
- **Voices.** Several named voices share the store with separate journals, identity files and scope. A Durable Object lease (`src/lease.ts`) stops two sessions writing the same voice at once.
- **Health telemetry.** Oura, Garmin, Withings and Cronometer connectors so the model can reason about sleep, training load and nutrition alongside the conversation.
- **Auth.** OAuth 2.1 with PKCE via `@cloudflare/workers-oauth-provider`; a small login page; a separate write-key door for machine writers.

Around sixty tools in total, registered in `src/index.ts`.

## Layout

```
src/
  index.ts        tool registration, OAuth, cron handlers
  storage.ts      R2 read/write, paths, arrival
  crypto.ts       AES-256-GCM
  kwindex.ts      keyword index (D1)
  embeddings.ts   vectors, hybrid search
  activation.ts   ACT-R activation ledger
  extraction.ts   nightly metadata extraction
  graph.ts        graph build and walk
  dream.ts        dream pass
  lease.ts        Durable Object lease
  oura.ts garmin.ts withings.ts cronometer.ts   health connectors
migrations/       D1 schema
scripts/          one-off migration, key generation, OAuth setup helpers
wrangler.jsonc    bindings (IDs replaced with placeholders)
```

## Running your own

You will need a Cloudflare account with Workers, R2, D1, Vectorize, Workers AI and Durable Objects enabled.

1. `npm install`
2. Create an R2 bucket, a D1 database and a Vectorize index (768 dimensions, cosine). Put their names/IDs in `wrangler.jsonc`.
3. `npm run generate-key` and set `ENCRYPTION_KEY` with `wrangler secret put`. Set `LOGIN_PASSWORD_HASH` likewise. Health connectors each need their own secrets; see the top of each connector file.
4. `npx wrangler d1 migrations apply <db>` to create the index tables.
5. `npm run deploy`, then add the worker's `/mcp` endpoint as a custom connector in Claude.

Rotate nothing you have not backed up: the encryption key cannot be changed without re-encrypting the bucket.

## Further reading

- [The Garden: an orienting memory for a language model](docs/garden-writeup.md) — what it is, how it is built, what a year of running it showed.
- [Athena: architecture note](docs/athena-architecture.md) — a companion agent-run research platform by the same operator.

## What is deliberately not here

Memory files, identity documents, journals, account identifiers, binding IDs, tokens. The operator's memories stay private by design; the code describes how they are held, not what they say.

## Licence

MIT.