Your notes, index and database stay in your AWS account. Only what an agent
retrieves goes to that agent's model.

See it work

Connect once, then ask in plain words. Memrain returns the evidence, cited to the
exact page. Your agent writes the answer.

claude mcp add --transport http memrain https://<subdomain>.<domain>/mcp \
  --header "Authorization: Bearer <token>"

See a full search with --explain

On the host, the CLI runs the same retrieval the MCP search tool does, and
--explain stamps per-signal ranking attribution on every hit:

docker exec deploy-memrain-1 bun run src/cli.ts search "<query>" --k 5 --explain

What you get

You write notes, decisions and code, and six months later neither you nor your
agent can find them. Memrain reads all of it once, keeps it searchable, and hands
that search to every MCP client you use, with the source attached.

What you get	Why it matters
Hybrid search	Vector and keyword arms fused with Reciprocal Rank Fusion. With the runtime defaults, a search makes one Titan embed call and no chat-model call.
Code intelligence	code_callers, code_callees, code_def, code_refs, code_blast (transitive callers, depth 5 by default, max 8) and code_flow, over TS/TSX, Python and Go.
Push context	volunteer_context surfaces relevant pages and volunteer_chronicle the recent timeline for the entities in play, before you ask. Both are deterministic, with no LLM call.
Facts, timelines, history	add_fact / recall / find_trajectory, the chronicle_* tools, and page_versions / page_revert for every page.
Chats and agent sessions	memrain transcripts ingest imports ChatGPT and Claude.ai exports, Codex CLI rollouts and Claude Code session logs, keeping what was said and redacting credentials.
Safe writes	request_id makes a retried write replay instead of landing twice; expected_version lets exactly one of two racing writers commit.
Team-ready	One connector for a team, a separate source per person through single-use enrollment codes, and daily USD caps per OAuth client, per PAT and per person. One person can be revoked or re-enrolled without touching the others.
Secrets redacted on write	Pasted AWS keys, API tokens and PEM keys become [REDACTED:<kind>:<fingerprint>] before they are stored or embedded.
Your infra	One Graviton t4g.medium instance and encrypted RDS Postgres 16, all in Terraform. Zero telemetry.

Every MCP tool is declared once in deploy/memrain/src/mcp/operations.ts; tools/list returns them with their schemas and annotations (readOnlyHint, and destructiveHint / idempotentHint on the writes), so a client can ask before it writes.

When Memrain is not the right fit

• You do not want to run an AWS account.
• You want a hosted service someone else operates.
• You want a chat UI. Memrain retrieves; composing the answer is the MCP client's job.

How it works

Memrain indexes your content ahead of time and answers searches on demand. It
returns ranked, cited chunks, never a generated answer, so the agent stays
grounded in what you actually wrote.

1. Notes and code come in from the markdown vault, indexed code roots, page_put, or POST /ingest.
2. Chunkers split them. Code is parsed with tree-sitter WASM grammars.
3. Titan v2 on Bedrock turns each chunk into an embedding.
4. Postgres with pgvector stores the vectors next to a keyword index and an entity graph.
5. Hybrid retrieval fuses the arms (RRF), applies boosts, de-duplicates and optionally reranks.
6. Cited results go back to the agent over /mcp.

A maintenance cycle runs every 6 hours (the shipped compose file sets
MEMRAIN_DREAM_INTERVAL_S=21600) to re-embed stale documents and keep the corpus tidy.

Every paid LLM feature (think, rerank, LLM intent and query expansion) is off
in the runtime code. scripts/init.sh opts a new install into a quality tier:
max by default, or MEMRAIN_INIT_TIER=free|balanced|max. The cost model is in
docs/HOW-IT-WORKS.md.

Request path in detail

sequenceDiagram
    autonumber
    actor You
    participant Agent as Your AI agent
    participant memrain as Memrain (MCP)
    participant DB as Postgres + pgvector
    You->>Agent: "What did I decide about X?"
    Agent->>memrain: tools/call search { q }
    memrain->>DB: vector + keyword + graph query
    DB-->>memrain: top chunks, ranked (RRF)
    memrain-->>Agent: cited chunks (evidence, not an answer)
    Agent-->>You: answer, grounded in your own notes

Quickstart (recommended: Terraform)

You need an AWS account with Bedrock access, Terraform >= 1.6, the
AWS CLI, and a domain on Cloudflare (or ingress_mode = "caddy" with
ports 80/443 open). Docker is not needed locally; bootstrap installs it on the
host.

1. Clone the repo

git clone https://github.com/<your-github-username>/memrain.git && cd memrain

2. Write your config (.env, terraform/terraform.tfvars, terraform/backend.hcl)

make init

3. Plan (runs the audit gate and terraform init)

make plan

4. Apply (does not run terraform init, so plan first)

make apply

5. Cloudflare mode: give the tunnel its token, then create the tunnel route
to the service in the Cloudflare dashboard.

aws secretsmanager put-secret-value \
  --secret-id <prefix>/cloudflared-tunnel-token --secret-string '<tunnel-token>'

6. Submit the Bedrock Anthropic use-case form once in the AWS console.
Without it every Claude call fails.

7. Index your vault (in an SSM session on the host)

docker exec deploy-memrain-1 bun run src/cli.ts reindex --source vault --vault /memory

8. Check health (expect {"ok":true,"db":...,"version":...})

curl -s https://<subdomain>.<domain>/health

9. Connect your agent

claude mcp add --transport http memrain https://<subdomain>.<domain>/mcp \
  --header "Authorization: Bearer <token>"

Try it locally without AWS infra

cd deploy/memrain && bun run src/cli.ts init --pglite

This creates ~/.memrain with an embedded PGLite database. Embeddings still call
Bedrock, so you need AWS credentials with Titan access.

Everything else (Caddy ingress, secrets, updates, verification) is in
docs/DEPLOYMENT.md.

Connect your agent and pick a credential

Every client connects to the same /mcp URL, with a bearer token or through
OAuth. What the caller can do depends on the credential:

Credential	How you get it	What it unlocks
Personal access token	memrain auth create <name> --source <src>	One person or machine, writing to its own source, with an optional daily cap.
OAuth 2.1 client	memrain auth register-client ...	Browser connectors (claude.ai, ChatGPT) and CLI sign-ins through /authorize, machine clients through client credentials, and enrollment mode for one connector shared by a team.
Static public bearer	Auto-generated in Secrets Manager as <prefix>/memrain-public-bearer	No tenant. Read tools such as search, page_get, backlinks and graph/entity reads; no code_*, think, query, get_chunks or volunteer_context. A small set of writes only with MEMRAIN_PUBLIC_WRITE=1.

Run the whoami tool to see the scopes, write source and read sources of the
credential you are using. Step-by-step guides, each with a troubleshooting table:

Client	Guide
Claude Code	docs/clients/CLAUDE_CODE.md
Codex CLI	docs/clients/CODEX.md
claude.ai (Pro, Max)	docs/clients/CLAUDE_AI.md
Claude Team, Enterprise	docs/clients/CLAUDE_TEAM.md
ChatGPT (developer mode, workspace apps)	docs/clients/CHATGPT.md

Deploy and operate

• Ingress. The default is a Cloudflare Tunnel with no inbound ports.
  ingress_mode = "caddy" serves Let's Encrypt TLS on 80/443 instead.
• Access. Reach the host through SSM (aws ssm start-session --target <instance-id>). No SSH.
• Update. cd /opt/memrain && git pull --ff-only && bash deploy/deploy.sh. It
  stamps the build, and /health must report the new stamp.
• Upgrading from before the rename. See UPGRADING.md; a
  plain pull and deploy is not enough.
• Operate. memrain doctor, memrain spend --days 7 and the /admin panel.
• Optional units. deploy/systemd ships a nightly eval probe and a bearer
  rotation timer. Bootstrap installs neither, and the static public bearer is
  meant to stay fixed; hand people PATs or OAuth clients instead.

See docs/DEPLOYMENT.md and docs/CONFIGURATION.md.

Security and tenancy

• Every route except GET /health, the OAuth metadata and flow endpoints and
  /admin (which has its own sign-in) needs a credential. /mcp is the agent contract.
• A built-in OAuth 2.1 server. Dynamic client registration is off unless
  MEMRAIN_ENABLE_DCR=1, and then the server boots only with
  MEMRAIN_OAUTH_REQUIRE_LOGIN=1 (or the explicit MEMRAIN_ENABLE_DCR_INSECURE=1).
• Enrollment codes are single-use, and only their SHA-256 is stored.
• Credentials pasted into pages, facts, timeline entries, indexed files or
  /ingest are redacted before storage by default
  (MEMRAIN_SECRET_SCAN_DISPOSITION=flag|reject changes that).
• For a capped caller, a paid call reserves its worst-case cost against the
  daily cap under a lock before it is sent.
• RDS is encrypted, deletion-protected and keeps a final snapshot. CloudTrail is
  on by default. Zero telemetry.

Details: docs/TEAM-SETUP.md and SECURITY.md.

Documentation

Doc	What is in it
docs/HOW-IT-WORKS.md	Retrieval pipeline, cost model, scoped credentials
docs/DEPLOYMENT.md	First install, tunnel or Caddy, updates, verification
docs/CONFIGURATION.md	Every env var, quality tiers, per-feature models and budgets
docs/TEAM-SETUP.md	One connector for a team, enrollment, budgets
docs/clients/	Connecting Claude Code, Codex, claude.ai, Claude Team and ChatGPT
ARCHITECTURE.md	Topology, containers, security model
CHANGELOG.md	Release history

Contributing

Memrain is deliberately small, so open an issue before anything that adds
infrastructure or changes the deploy story. Before sending a change, run the
local gates:

make audit
make scrub-audit
make typecheck                          # src/ and tests/
make test
env -C deploy/memrain bun run test:sharded

Never run a bare full bun test: the embedded database runs out of memory
mid-run and reports failures that are not real. See
CONTRIBUTING.md.

Security

Please do not open a public issue for a vulnerability. Report it privately as
described in SECURITY.md.

License

MIT.