From e1a3a296e4eb78d0cd5ab022cd78dfd1622e2d5b Mon Sep 17 00:00:00 2001 From: ThreeLight2000 <54524378+ThreeLight2000@users.noreply.github.com> Date: Fri, 2 Oct 2026 02:14:00 +0900 Subject: [PATCH] docs: clarify project purpose and engineering evidence --- README.ko.md | 119 +++++++++++++++++++++++++++++++ README.md | 197 ++++++++++++++++++--------------------------------- 2 files changed, 188 insertions(+), 128 deletions(-) create mode 100644 README.ko.md diff --git a/README.ko.md b/README.ko.md new file mode 100644 index 0000000..259ca2a --- /dev/null +++ b/README.ko.md @@ -0,0 +1,119 @@ +# Context OS + +작업 맥락을 기록하고 다른 환경에서 다시 꺼내 볼 수 있도록 하는 오픈소스 클라이언트와 개인 맥락 서버입니다. + +[English](README.md) · [설치 모드](docs/setup-modes.md) · [Context API](apps/server-context/README.md) · [MCP 어댑터](apps/server-mcp/README.md) · [MIT](LICENSE) + +브라우저 페이지에 생각을 남기거나 프로젝트의 브라우저 세션을 보관하고, Raycast에서 짧은 메모를 기록할 수 있습니다. 다시 돌아오면 관련 기록을 조회하거나 선택적인 MCP 도구로 저장한 결정과 다음 할 일을 읽습니다. Chrome은 서버 없이 시작할 수 있습니다. Raycast와 Context 기록을 공유하려면 두 클라이언트가 접근할 수 있는 Context API가 필요합니다. + +**Context OS와 [StateCarry](https://github.com/ThreeLightStudio/statecarry)는 작업 복귀의 서로 다른 부분을 다룹니다.** Context OS는 기록 클라이언트, 저장소, 조회 인터페이스를 제공합니다. StateCarry는 선택한 프로젝트 대화와 현재 프로젝트 관찰을 분석해 방향과 다음 판단을 검토하도록 돕습니다. 이 저장소가 둘 사이의 자동 통합을 입증하지는 않습니다. + +## 기록을 어디에 보관할지 선택하기 + +| 구성 | 시작 방법 | 데이터 경계 | +| --- | --- | --- | +| Chrome만 사용 | 확장을 빌드하고 첫 실행에서 **로컬로 시작**을 선택합니다. | 브라우저 작업 맥락은 해당 확장의 Chrome 로컬 저장소에 남습니다. Raycast가 직접 읽을 수 없습니다. | +| 로컬 Chrome + Raycast | Wrangler와 로컬 D1으로 `server-context`를 실행하고 URL·기기 토큰으로 양쪽을 연결합니다. | 공유 Context 기록은 로컬 D1에 저장하고 Chrome 프로젝트·세션 상태는 별도 클라이언트 저장소에 둡니다. | +| 개인 Cloudflare Worker + D1 | 직접 Context Server를 설정·배포하고 URL과 권한별 기기 토큰으로 연결합니다. | 공유 기록이 기기를 떠나 개인 Cloudflare 배포에 저장됩니다. 직접 운영하는 구성으로, 관리형 동기화 서비스가 아닙니다. | + +확장 origin, 토큰 생성, 로컬 DB 준비, 명시적인 원격 migration·배포 단계는 [설치 모드 가이드](docs/setup-modes.md)를 따르세요. API로 Context 기록을 공유한다고 해서 브라우저 내부 프로젝트·세션 설정까지 모두 동기화되는 것은 아닙니다. + +## 확인할 세 가지 경계 + +| 결정 | 의미 | 공개 근거 | +| --- | --- | --- | +| Chrome 로컬 저장과 Worker/D1 기록 저장을 구분합니다. | 서버 연결은 명시적인 데이터 위치 선택입니다. 다른 클라이언트가 Chrome 저장소에 접근할 수 있게 되는 것은 아닙니다. | [Chrome 저장 구현](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/client-chrome/src/storage.ts) · [클라이언트 가이드](apps/client-chrome/README.md) | +| 작은 텍스트 기록을 검증하고 기기 토큰의 권한으로 보호합니다. | 같은 ID의 동일 요청 재시도는 중복 저장하지 않고, 다른 내용이면 충돌합니다. 기록 쓰기는 추가 방식이며, 별도 `delete` 권한으로 제거할 수 있습니다. | [API 구현](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-context/src/index.ts) · [기록 검증](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-context/src/record.ts) · [API 테스트 사례](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-context/test/index.test.ts) | +| MCP와 Brain을 Context API 위의 선택적인 서비스로 둡니다. | MCP는 D1에 직접 접근하지 않고 쓰기 모드에서도 새 리비전을 추가합니다. Brain은 기록 DB를 복제하지 않고 모델 호출과 결과 검증을 담당합니다. | [MCP 도구](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-mcp/src/tools.ts) · [MCP 테스트 사례](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-mcp/test/tools.test.ts) · [Brain 실행기](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-brain/src/tasks/task-runner.ts) | + +Context API는 크기가 제한된 텍스트와 지원하는 메타데이터를 받습니다. 첨부 파일·스크린샷·HTML·DOM 콘텐츠 업로드는 지원하지 않습니다. D1에는 토큰의 해시를 저장합니다. 원래 토큰, 실제 설정, 기록 데이터는 Git에 넣지 마세요. 제한과 권한은 [서버 계약](apps/server-context/README.md)에 있습니다. + +## 로컬에서 시작하기 + +워크스페이스는 pnpm **11.21.0**과 Turborepo를 사용합니다. 저장소 루트에서 실행하세요. + +```sh +pnpm install +pnpm --filter context-shelf build +``` + +`chrome://extensions`에서 `apps/client-chrome/dist`를 압축 해제된 확장으로 로드하고 로컬 저장을 선택합니다. [Chrome 가이드](apps/client-chrome/README.md)를 참고하세요. + +Raycast와 기록을 공유하려면 [로컬 Worker/D1 설치](docs/setup-modes.md)를 이어서 진행합니다. `apps/server-context/wrangler.jsonc.example`을 개인 `wrangler.jsonc`로 복사하고, `.dev.vars`에 정확한 확장 origin을 지정하며, **로컬** migration과 읽기·쓰기 토큰 생성을 수행합니다. Raycast는 `pnpm --filter context-os build`로 빌드한 뒤 **Import Extension**으로 `apps/client-raycast/dist`를 가져옵니다. 실제 클라이언트에서 기록을 한 번 확인하세요. [Raycast 가이드](apps/client-raycast/README.md)를 참고하세요. + +루트에서 사용하는 개발 명령입니다. + +```sh +pnpm dev:chrome +pnpm dev:raycast +pnpm dev:server +pnpm dev:brain +pnpm --filter server-mcp dev +``` + +선택한 구성에 필요한 서비스만 실행합니다. Context Server는 개인 설정과 로컬 DB 준비가 먼저 필요합니다. Brain과 MCP도 아래 환경 설정과 의존 서비스를 준비해야 합니다. + +## 선택 기능 + +### MCP: 기록 읽기와 리비전 추가 + +MCP는 기존 Context API를 HTTP로 호출합니다. 복사한 환경 파일에 `CONTEXT_SERVER_URL`과 `CONTEXT_SERVER_TOKEN`을 설정하세요. + +```sh +cp apps/server-mcp/.env.example apps/server-mcp/.env +pnpm --filter server-mcp build +pnpm --filter server-mcp start +``` + +기본은 읽기 전용입니다. `CONTEXT_MCP_MODE=read-write`로 `create_context`와 `update_context`를 추가할 수 있습니다. 업데이트는 기존 기록을 수정하지 않고 새 리비전을 추가합니다. Streamable HTTP를 사용하려면 별도 `CONTEXT_MCP_HTTP_TOKEN`을 설정하고 다음 명령을 실행합니다. + +```sh +pnpm --filter server-mcp start:http +``` + +로컬 엔드포인트는 `http://127.0.0.1:17003/mcp`입니다. HTTP bearer 토큰은 MCP를 보호하고 Context 기기 토큰은 기록 접근 권한을 따로 제어합니다. 클라이언트 설정과 전송 방식은 [MCP 가이드](apps/server-mcp/README.md)에 있습니다. + +### Brain: 선택적인 모델 분석 + +Brain은 별도의 로컬 Node 서비스입니다. 로컬 OpenAI 호환 모델 런타임과 `BRAIN_MODEL`을 설정하면 `summarize` 같은 Action이 검증된 구조화 결과를 반환합니다. `daily-summary`에는 Context API URL·토큰도 필요하며 Chrome에서 사용하려면 `BRAIN_ALLOWED_ORIGINS`에 정확한 확장 origin을 지정합니다. + +```sh +cp apps/server-brain/.env.example apps/server-brain/.env +pnpm --filter server-brain build +pnpm --filter server-brain start +``` + +Brain은 D1을 대체하거나 Context 기록을 별도 DB에 복제하지 않습니다. 모델 요청은 설정한 런타임으로 보내므로 비공개 기록을 전송하기 전에 주소를 확인하세요. 현재 제공자 레지스트리는 `local` 제공자를 지원합니다. [Brain 가이드](apps/server-brain/README.md)와 [제공자 설정](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-brain/src/config.ts)을 참고하세요. + +### 외부 gateway: 경로 계약 + +선택적인 계약은 `/v1/*`를 Context Server로, `/mcp`를 MCP로 연결합니다. `/brain/v1/*`는 예약 경로이며 초기에는 로컬 전용입니다. 공급자 중립적인 [외부 진입점 계약](docs/external-entrypoint.md)이 있다는 사실만으로 gateway·Tunnel·호스팅된 upstream 배포를 확인할 수는 없습니다. 기존 클라이언트는 Worker URL을 계속 직접 사용할 수 있습니다. + +## 저장소 구성 + +| 경로 | 책임 | +| --- | --- | +| [`apps/client-chrome`](apps/client-chrome/README.md) | Context Shelf Chrome 확장, 로컬 프로젝트·세션·URL 기억과 기록 클라이언트 | +| [`apps/client-raycast`](apps/client-raycast/README.md) | Raycast 기록·조회 클라이언트 | +| [`apps/server-context`](apps/server-context/README.md) | Worker + D1 Context/Data API, 기록 검증과 기기 토큰 권한 | +| [`apps/server-brain`](apps/server-brain/README.md) | 선택적인 로컬 모델 오케스트레이션과 작업 수명주기 | +| [`apps/server-mcp`](apps/server-mcp/README.md) | 선택적인 stdio / Streamable HTTP MCP 어댑터 | +| [`apps/server-gateway`](apps/server-gateway) | 외부 진입점 계약 | + +`client-mobile`은 향후 클라이언트용으로 예약되어 있습니다. 공유 패키지는 안정적인 클라이언트 간 계약을 추출할 필요가 생길 때 추가합니다. + +## 상태, 검사, 기존 설치 전환 + +이 저장소는 소스와 설치 가이드를 제공하며 2026년 10월 2일 기준 GitHub Release는 없습니다. 소스 버전 [`019e405`](https://github.com/ThreeLightStudio/context-os/commit/019e405264b241241fe2fc2bfb6766f450ff613c)의 [CI는 성공](https://github.com/ThreeLightStudio/context-os/actions/runs/32220575284)했습니다. 이 결과가 특정 서비스의 배포, 실제 모델 결과, 기기에서의 수락을 입증하지는 않습니다. + +```sh +pnpm verify +``` + +루트 명령은 저장소 테스트와 각 패키지의 lint·타입 검사·테스트·빌드를 실행합니다. Brain 테스트는 모의 모델 제공자를 사용합니다. Raycast UI를 변경한 경우 재빌드한 확장을 실제 Raycast에서 확인해야 하며 빌드만으로 완료되지 않습니다. + +예전 Chrome 빌드를 바꿀 때는 확장 ID를 먼저 확인하세요. 저장소·단축키·허용 origin은 ID에 연결됩니다. 새 origin과 연결을 설정한 뒤 이전 빌드를 비활성화합니다. 두 설치는 같은 내용을 서로 다른 기록 ID로 남길 수 있습니다. 서버는 한 ID의 동일 요청 재시도만 중복 제거합니다. Raycast의 패키지 ID는 `context-os`입니다. **Import Extension**이 의도한 설치를 갱신하는지 확인하고, **Context Settings**와 기록 동작을 검사한 뒤 이전 설치를 제거하세요. 자세한 절차는 [설치 모드](docs/setup-modes.md)와 클라이언트 가이드에 있습니다. + +## 라이선스 + +[MIT](LICENSE). diff --git a/README.md b/README.md index 597d95f..47d99b6 100644 --- a/README.md +++ b/README.md @@ -1,116 +1,63 @@ # Context OS -Open-source clients and a personal context server for capturing work and -resuming it across environments. - -## Repository layout - -```text -apps/ -├── client-chrome/ # Local-first Chrome extension -├── client-raycast/ # Raycast extension -├── server-context/ # Cloudflare Worker + D1 Context/Data API -├── server-brain/ # Local-first AI orchestration and execution API -├── server-mcp/ # Local stdio MCP adapter for Context OS -└── server-gateway/ # Provider-neutral external entry-point contract -``` +Open-source clients and a personal context server for capturing work context and retrieving it when you resume across environments. -`client-mobile/` is reserved for a future mobile client. Shared packages will -be added only when a stable cross-client contract needs to be extracted. +[한국어](README.ko.md) · [Setup modes](docs/setup-modes.md) · [Context API](apps/server-context/README.md) · [MCP adapter](apps/server-mcp/README.md) · [MIT](LICENSE) -## 개발 +Save a thought next to a browser page, keep a project's browser session, or capture a short note from Raycast. When you return, retrieve the relevant records or use the optional MCP tools to read a saved decision or next step. Chrome can start without a server; sharing Context records with Raycast requires a Context API that both clients can reach. -This repository uses pnpm workspaces and Turborepo. +**Context OS and [StateCarry](https://github.com/ThreeLightStudio/statecarry) solve different parts of returning to work.** Context OS provides capture clients, record storage, and retrieval interfaces. StateCarry analyzes selected project conversations and current project observations to help review a direction and next decision. This repository does not establish an automatic integration between the two. -```sh -pnpm install -pnpm verify -``` +## Choose where records live -Run one package with a root filter: +| Setup | Start here | Data boundary | +| --- | --- | --- | +| Chrome only | Build the extension and choose **Start locally** on first launch. | Browser work contexts stay in the extension's Chrome-local storage. Raycast cannot read that storage directly. | +| Local Chrome + Raycast | Run `server-context` with Wrangler and local D1, then connect both clients with its URL and a device token. | Shared Context records live in local D1; Chrome's project/session state remains separate client storage. | +| Your Cloudflare Worker + D1 | Configure and deploy your own Context Server, then connect clients to its URL with scoped device tokens. | Shared records leave the device for your Cloudflare deployment. This is a self-hosted setup, not a managed synchronization service. | -```sh -pnpm dev:chrome -pnpm dev:raycast -pnpm dev:server -pnpm dev:brain -pnpm dev:mcp -``` +Follow [setup modes](docs/setup-modes.md) for extension origins, token creation, local database setup, and the explicit remote migration/deployment steps. Sharing Context records through the API does not mean every browser-local project or session setting is synchronized. -Build the client bundles: +## Three boundaries to inspect -```sh -pnpm --filter context-shelf build -pnpm --filter context-os build -``` - -## 설치 모드 선택 - -데이터를 보관할 위치에 따라 하나를 선택하세요. +| Decision | Practical consequence | Public evidence | +| --- | --- | --- | +| Keep Chrome-local persistence distinct from the Worker/D1 record store. | A server connection is an explicit data-location choice; another client does not gain access to Chrome storage. | [Chrome storage](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/client-chrome/src/storage.ts) · [Client guide](apps/client-chrome/README.md) | +| Validate small text records behind scoped device tokens. | An exact retry of the same record ID is idempotent; different content under that ID conflicts. Capture writes append records, while a separate `delete` scope permits removal. | [API implementation](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-context/src/index.ts) · [Record validation](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-context/src/record.ts) · [API fixtures](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-context/test/index.test.ts) | +| Keep MCP and Brain as optional services over the Context API. | MCP has no direct D1 access; its write mode appends revisions. Brain owns model calls and validates their output without duplicating the record database. | [MCP tools](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-mcp/src/tools.ts) · [MCP fixtures](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-mcp/test/tools.test.ts) · [Brain task runner](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-brain/src/tasks/task-runner.ts) | -| Setup | Best for | Data location | Main components | -| --- | --- | --- | --- | -| [완전 로컬](docs/setup-modes.md#1-완전-로컬-chrome--raycast--workerd1) | 한 대의 컴퓨터와 오프라인 사용 | Chrome 로컬 저장소 또는 로컬 Worker + D1 | Chrome, 선택적으로 Raycast | -| [Cloudflare D1 동기화](docs/setup-modes.md#2-cloudflare-d1-동기화) | Raycast, 여러 클라이언트, 여러 기기 | 내 Cloudflare Worker + D1 | clients + `server-context` | +The Context API accepts bounded text captures and supported metadata. It does not upload attachments, screenshots, HTML, or DOM content. Tokens are stored as hashes in D1; keep raw tokens, actual configuration, and captured data out of Git. See the [server contract](apps/server-context/README.md) for limits and permissions. -Chrome은 서버 없이 로컬로 시작한 뒤 나중에 연결할 수 있습니다. Raycast는 -Chrome 로컬 저장소를 읽지 않으므로 로컬 Worker/D1 또는 Cloudflare Worker가 -필요합니다. 자세한 설치, 배포, 보안 확인 절차는 [설치 모드 가이드](docs/setup-modes.md)를 -따르세요. +## Start locally -## Context Server와 D1 - -The server is deployed independently from `apps/server-context`. Copy the -public configuration template before local development: +The workspace pins pnpm **11.21.0** and uses Turborepo. From the repository root: ```sh -cd apps/server-context -cp wrangler.jsonc.example wrangler.jsonc -pnpm db:migrate:local -pnpm dev +pnpm install +pnpm --filter context-shelf build ``` -The production resource names are `server-context` for the Worker and -`db-context` for the D1 database. The package name is also `server-context`, -so root commands use `pnpm --filter server-context ...`. +Load `apps/client-chrome/dist` as an unpacked extension at `chrome://extensions`, then choose local storage. See the [Chrome guide](apps/client-chrome/README.md). -원격 명령을 실행하기 전 자신의 D1 database ID, 고유 rate-limit namespace ID, -브라우저 origin을 입력하세요. 실제 `wrangler.jsonc`, `.dev.vars`, API token, -기록 데이터는 절대 커밋하지 않습니다. +For shared records with Raycast, continue with the [local Worker/D1 setup](docs/setup-modes.md). Its steps include copying `apps/server-context/wrangler.jsonc.example` to your private `wrangler.jsonc`, setting the exact extension origin in `.dev.vars`, applying **local** migrations, and creating a local read/write token. Build Raycast with `pnpm --filter context-os build`, import `apps/client-raycast/dist` using Raycast's **Import Extension**, and verify a capture in the actual client. See the [Raycast guide](apps/client-raycast/README.md). -Remote migrations and deployment are explicit side-effectful operations: +Development commands from the root: ```sh -pnpm --filter server-context db:migrate:remote -pnpm --filter server-context run deploy +pnpm dev:chrome +pnpm dev:raycast +pnpm dev:server +pnpm dev:brain +pnpm --filter server-mcp dev ``` -Clients connect to the deployed Worker URL and a device token. Moving the -source into this monorepo does not change the API or D1 data. - -## 선택 기능: Server Brain - -`apps/server-brain` is an independent local Node server for AI orchestration. -Clients call stable Actions such as `summarize` without knowing the model or -prompt. The server uses an OpenAI-compatible local inference endpoint by -default and validates structured results before returning them. - -```sh -pnpm --filter server-brain build -pnpm --filter server-brain start -``` +Run only the components your chosen mode needs. `server-context` requires its private configuration and local database setup first. Brain and MCP require their environment settings and dependencies below. -`server-context` remains the Context/Data Layer: it owns D1, records, and the -`/v1/records` API. `server-brain` is the Intelligence/Execution Layer: it -owns Actions, Context resolution hooks, model providers, and task lifecycle. -이는 선택 기능입니다. 모델 제공자 설정과 API 예시는 -[`apps/server-brain/README.md`](apps/server-brain/README.md)를 참조하세요. +## Optional services -## Context OS MCP Server +### MCP: read records or append revisions -`apps/server-mcp` exposes read and append-only Context OS tools through stdio or -Streamable HTTP MCP transport. It calls `server-context` over its existing HTTP -API and never accesses D1 directly. +MCP calls the existing Context API over HTTP. Configure `CONTEXT_SERVER_URL` and `CONTEXT_SERVER_TOKEN` in the copied environment file: ```sh cp apps/server-mcp/.env.example apps/server-mcp/.env @@ -118,61 +65,55 @@ pnpm --filter server-mcp build pnpm --filter server-mcp start ``` -For the Streamable HTTP connection form, use `pnpm start:mcp:http`. It listens -at `http://127.0.0.1:17003/mcp` and requires the separate -`CONTEXT_MCP_HTTP_TOKEN` bearer token. The default mode is read-only. Set -`CONTEXT_MCP_MODE=read-write` only when the MCP client should be allowed to -append records. See -[`apps/server-mcp/README.md`](apps/server-mcp/README.md) for Codex and Claude -Desktop and ChatGPT connection examples. +The default mode is read-only. Set `CONTEXT_MCP_MODE=read-write` to add `create_context` and `update_context`; an update appends a new revision rather than mutating a record. For Streamable HTTP, set a separate `CONTEXT_MCP_HTTP_TOKEN` and run: + +```sh +pnpm --filter server-mcp start:http +``` + +The local endpoint is `http://127.0.0.1:17003/mcp`. The HTTP bearer token protects MCP; the Context device token independently controls access to records. See the [MCP guide](apps/server-mcp/README.md) for client configuration and transport details. -## Migrating existing installations +### Brain: opt-in model analysis -The server being shared does not make old and new client installations the -same client. Check the client identity before switching from a pre-monorepo -build. +Brain is a separate local Node service. Configure a local OpenAI-compatible model runtime and `BRAIN_MODEL`; actions such as `summarize` return validated structured output. For `daily-summary`, also configure the Context API URL/token and the exact Chrome origin in `BRAIN_ALLOWED_ORIGINS` when using Chrome. -### Chrome extension +```sh +cp apps/server-brain/.env.example apps/server-brain/.env +pnpm --filter server-brain build +pnpm --filter server-brain start +``` -The extension manifest does not currently pin a public key, so a new unpacked -build may receive a different extension ID. Chrome storage, shortcuts, and -extension origins are tied to that ID. +Brain does not replace D1 or persist a second copy of Context records. Its model request goes to the configured runtime; review that endpoint before sending private captures. The current provider registry supports the `local` provider. See the [Brain guide](apps/server-brain/README.md) and [provider configuration](https://github.com/ThreeLightStudio/context-os/blob/019e405264b241241fe2fc2bfb6766f450ff613c/apps/server-brain/src/config.ts). -When testing a new build: +### External gateway: a route contract -1. Load the new `apps/client-chrome/dist` from `chrome://extensions` and note - its ID. -2. Add the new ID to the private `ALLOWED_ORIGINS` value in - `apps/server-context/wrangler.jsonc`. Multiple origins may be separated by - commas while both versions are being tested. -3. Deploy the server configuration before testing remote sync. -4. Configure the server URL and API token in the new extension. -5. Disable the old extension after verification. +The optional contract maps `/v1/*` to Context Server and `/mcp` to MCP. `/brain/v1/*` is reserved and initially local-only. The provider-neutral [external entry-point contract](docs/external-entrypoint.md) does not establish that a gateway, Tunnel, or hosted upstream is deployed. Existing clients can continue using their Worker URL directly. -Do not run both versions as daily drivers. Both can register the same shortcut, -and each capture creates a new record ID. The server only deduplicates an exact -retry of the same record ID; it does not merge captures from two installations. +## Repository map -### Raycast extension +| Path | Responsibility | +| --- | --- | +| [`apps/client-chrome`](apps/client-chrome/README.md) | Context Shelf Chrome extension; local project/session/URL memory and capture client | +| [`apps/client-raycast`](apps/client-raycast/README.md) | Raycast capture and retrieval client | +| [`apps/server-context`](apps/server-context/README.md) | Worker + D1 Context/Data API, record validation, and device-token scopes | +| [`apps/server-brain`](apps/server-brain/README.md) | Optional local model orchestration and task lifecycle | +| [`apps/server-mcp`](apps/server-mcp/README.md) | Optional stdio / Streamable HTTP MCP adapter | +| [`apps/server-gateway`](apps/server-gateway) | External entry-point contract | -The Raycast extension keeps the package identity `context-os`. Import the -generated `apps/client-raycast/dist` using Raycast's **Import Extension** action -and verify that the existing extension is updated rather than installed as a -second command set. Confirm the Context Settings command and run one capture -before removing or disabling any older installation. +`client-mobile` is reserved for a future client. Shared packages are deferred until a stable cross-client contract needs extraction. -## 외부 진입점과 운영 방식 +## Status, checks, and existing installations -Context OS는 서비스를 하나로 합치지 않고, 선택적인 단일 public origin 뒤에서 경로로 분리해 운영할 수 있습니다. +This repository publishes source and setup guides; no GitHub Release is available as of October 2, 2026. [CI succeeded](https://github.com/ThreeLightStudio/context-os/actions/runs/32220575284) at source revision [`019e405`](https://github.com/ThreeLightStudio/context-os/commit/019e405264b241241fe2fc2bfb6766f450ff613c). That observation does not prove a particular deployed service, real model result, or device acceptance. -- `/v1/*` → `server-context` -- `/mcp` → `server-mcp` -- `/brain/v1/*` → 초기에는 local-only 예약 경로 +```sh +pnpm verify +``` -지원하는 운영 방식은 전부 로컬, Hybrid, Public gateway입니다. 전부 로컬에서는 `server-context`를 Wrangler/local D1, `server-mcp`를 stdio 또는 로컬 HTTP, `server-brain`을 로컬 Node와 local LLM으로 실행합니다. Hybrid에서는 로컬 MCP/Brain이 배포된 Context Worker를 호출하고, Public gateway에서는 하나의 origin이 `/v1/*`와 `/mcp`를 각 서비스로 전달합니다. 초기에는 `/brain/v1/*`을 외부에 공개하지 않습니다. +The root command runs repository tests and package lint, type, test, and build tasks. Brain tests use mock model providers. After changing a Raycast UI, verify the rebuilt extension in Raycast; a build alone is insufficient. -로컬 포트는 개발용이며 public API 계약이 아닙니다. 기존 `server-context` Worker, D1, migration, token 운영과 직접 Worker URL을 사용하는 기존 클라이언트는 변경 없이 유지됩니다. 자세한 경계와 구성 예시는 [`docs/external-entrypoint.md`](docs/external-entrypoint.md)를 참고하세요. +When replacing an older Chrome build, check its extension ID before switching: storage, shortcuts, and allowed origins belong to that ID. Configure the new origin and connection before disabling the old build. Two installations can create separate record IDs for the same capture; the server only deduplicates exact retries of one ID. Raycast keeps the `context-os` package identity; confirm **Import Extension** updates the intended installation, check **Context Settings**, and test a capture before removing an older installation. See [setup modes](docs/setup-modes.md) and the client guides for the full checks. ## License -MIT +[MIT](LICENSE).