Cloudflare Memory MCP

opencode를 위한 프로젝트별 메모리 MCP 서버로, 전적으로 Cloudflare 무료 티어에서 호스팅됩니다:

• 노트 — 태그와 유형이 있는 단순 키 기반 메모리

• 벡터 — Vectorize를 통한 의미 기반 검색(임베딩은 Wokers AI @cf/baai/bge-m3, 1024차원, 다국어)

• 그래프 — D1(SQLite)의 엔티티 및 관계를 재귀적으로 탐색

• 웹 대시보드 — 브라우저에서 /를 열면 메모리가 있는 모든 프로젝트를 볼 수 있습니다. 각 프로젝트 카드를 열면 엔티티와 관계의 인터랙티브 힘 기반(force-directed) 그래프가 있는 상세 보기가 표시되고(휠 = 확대/축소, 드래그 = 패닝, 더블클릭 또는 버튼 = 초기화, 마우스를 올리면 = 이웃이 강조됨), Delete project 버튼으로 프로젝트, 노트, 그래프, FTS 행, 캐시, 벡터 임베딩을 모두 제거할 수 있습니다.

opencode ── MCP (streamable HTTP + Bearer auth) ──> Worker
                                                     ├─ Vectorize   memory-vectors (namespace per project)
                                                     ├─ D1          projects / notes / nodes / edges / FTS5
                                                     ├─ Workers AI  bge-m3 embeddings
                                                     └─ KV          recent-memories cache

스크린샷

프로젝트 목록

대시보드에는 계정에 등록된 모든 프로젝트가 메모리, 엔티티, 관계, 그리고 마지막 활성 시점의 건수와 함께 나열됩니다.

지식 그래프

프로젝트를 열면 메모리와 그래프를 살펴볼 수 있습니다. 그래프는 곡선 형태의 방향성 엣지, 마우스 호버 강조, 호휠 줌, 드래그 패닝, 초기화 컨트롤을 지원합니다.

Related MCP server: MCP Memory

폴더 격리 방식

서버는 MCP 세션을 Durable Object(무료 티어, SQLite 백엔드) 내부에서 실행하며, 세션의 모든 메시지를 하나의 isolate에 고정합니다. 프로젝트 식별자는 다음 순서로 결정됩니다.

1. project_root 툴 인자(권장) — 작업 폴더를 어떤 도구에든 전달합니다. 예: remember({ project_root: "D:/Projects/foo", content: ... }). 서버는 정규화된 경로의 해시 값을 안정적인 프로젝트 ID로 만들고 세션의 남은 기간 동안 프로젝트를 기억하므로, 이후 호출에서는 파라미터를 생략해도 됩니다. 명시적으로 고정하려면 identify_project 도구가 있습니다.

2. project_id 툴 인자 — 명시적 ID(세션 동안 캐시됩니다).

3. x-project-root / x-project-id 헤더 — 헤더로 지정하도록 구성한 클라이언트용.

4. MCP 루트 — 클라이언트가 지원할 때 자동으로 폴더를 감지합니다.

식별자는 정규화된 경로의 해시일 뿐이므로, 파일 세트의 다른 절대 경로로 열어도 동일한 프로젝트로 귀결됩니다. 모든 읽기와 쓰기는 그 ID로 범위가 고정됩니다. Vectorize 조회는 프로젝트별 네임스페이를 사용하고, 모든 D1 조회는 project_id로 필터링하므로 서로 다른 두 폴더가 서로의 메모리를 볼 수 없습니다.

opencode에서 사용

opencode는 자체 작업 디렉터리(사용자의 bash cwd)를 알고 있습니다. 에이전트는 세션당 한 번만 그것을 전달하면 됩니다. 이 저장면에는 복사하여 바로 쓸 수 있는 템플릿이 **AGENTS.md**로 포함되어 있습니다. 메모리를 넣고 싶은 모든 프로젝트로 복사하고 PROJECT_ROOT를 해당 프로젝트의 디렉터리로 설정하면, 에이전트가 식별자를 자동으로 처리합니다.

When using the memory MCP tools, pass project_root (your bash cwd) on the first
memory call of the session.

설정

사전 준비 사항: Node 18+, Cloudflare 계정, 그리고 한 번만 수행할 npx wrangler login입니다.

npm install
npm run setup        # creates D1 db, KV namespace, Vectorize index; patches wrangler.toml
npm run db:migrate:remote
npx wrangler secret put MEMORY_AUTH_TOKEN   # optional but strongly recommended
npm run deploy

엔드포인트는 다음과 같습니다.

• MCP: https://cloudflare-memory-mcp.<your-subdomain>.workers.dev/mcp

• Dashboard: https://cloudflare-memory-mcp.<your-subdomain>.workers.dev/

로컬 개발:

npm run dev              # wrangler dev --local  (AI + Vectorize are remote-only)
npm run db:migrate:local

opencode 연동

하나의 진입점이면 모든프로젝트에서 동일하게 동작합니다. 프로젝트별 값이 필요 없습니다.

// ~/.config/opencode/opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "memory": {
      "type": "remote",
      "url": "https://cloudflare-memory-mcp.<your-subdomain>.workers.dev/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MEMORY_AUTH_TOKEN}"
      }
    }
  }
}

그 이후의 프로젝트 식별은 에이전트가 맡습니다. 각 세션의 첫 번째 메모리 호출이에서 작업 디렉터리 폴더를 project_root로 전달하고(위AGENTS.md 팁 참고) 부터는 서버가 그 폴더 기준으로 모든 것을 검색합니다.

대시보드(/)는 동일한 MEMORY_AUTH_TOKEN을 한 번 요청하고 localStorage에 저장합니다. MEMORY_AUTH_TOKEN을 설정하지 않으면 모든 것이 공개되므로 개인!용 또는 임시 실험에서만 그렇게 하세요.

MCP 도구

모든 도구는 project_pos(폴더 경로 또는 file:// URI)와 project_id를 선택적으로 받으며, 세션에서 한쪽이라도 전달되면 기억됩니다.

무료 티어 상한

벡터 상한에 근접하게 될 경우 설계 여지를 활용할 수 있습니다: 영구적으로 필요한 메모만 참고("remember" with type: "decision" | "fact")하고 돼지의 긴 분냥열은 search_memory(FTS5, 상한 없음)에 스토리지 하거나, 또는 bge-small(384차원, 영어 전용)로 인덱스를 다시 만들어 용량을 약 3배 확보합니다.

프로젝트 구조

src/index.ts      fetch router: dashboard, /api/*, /mcp -> Durable Object
src/session-do.ts MCP session host (Durable Object): sessions, SSE, roots, identity
src/tools.ts      the 10 tool definitions (zod schemas + implementations)
src/store.ts      D1 / Vectorize / KV data layer
src/identity.ts   project-id derivation from folder roots
src/embed.ts      Workers AI bge-m3 embeddings
src/api.ts        dashboard API (projects, detail, graph, delete)
src/web.ts        dashboard page (token-gated)
migrations/       D1 schema
scripts/setup.mjs  creates Cloudflare resources and patches wrangler.toml
AGENTS.md          template to copy into projects that use this memory server