memex

memex is a self-hosted memory server for your AI agents. It indexes your markdown notes and your code (TypeScript, Python, Go, Bash, SQL), and it answers any MCP client with cited evidence from hybrid vector + keyword + entity-graph search.

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. memex returns the evidence, cited to the exact page. Your agent writes the answer.

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

docker exec deploy-memex-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. memex reads all of it once, keeps it searchable, and hands that search to every MCP client you use, with the source attached.

91 MCP tools, each declared once in deploy/memex/src/mcp/operations.ts; tools/list returns them with their schemas.

When memex 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. memex retrieves; composing the answer is the MCP client's job.

How it works

memex 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 MEMEX_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 MEMEX_INIT_TIER=free|balanced|max. The cost model is in docs/HOW-IT-WORKS.md.

sequenceDiagram
    autonumber
    actor You
    participant Agent as Your AI agent
    participant memex as memex (MCP)
    participant DB as Postgres + pgvector
    You->>Agent: "What did I decide about X?"
    Agent->>memex: tools/call search { q }
    memex->>DB: vector + keyword + graph query
    DB-->>memex: top chunks, ranked (RRF)
    memex-->>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>/memex.git && cd memex

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-memex-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 memex https://<subdomain>.<domain>/mcp \
  --header "Authorization: Bearer <token>"

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

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

Connect your agent and pick a credential

Claude Code, Cursor and Codex all connect to the same /mcp URL with the same Authorization: Bearer header. What the caller can do depends on the credential:

Run the whoami tool to see the scopes, write source and read sources of the credential you are using. Client setup: deploy/memex/docs/CLAUDE-CODE.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/memex && git pull --ff-only && bash deploy/deploy.sh. It stamps the build, and /health must report the new stamp.
• Operate. memex doctor, memex spend --days 7 and the /admin panel.
• Optional units. deploy/systemd ships a nightly eval probe and a bearer rotation timer. Bootstrap does not install either.

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 MEMEX_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 (MEMEX_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

Contributing

memex 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/memex 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.