context

# @context - professional context manager @context is a self-hosted context manager. It organizes your work context into a private CRM and knowledge base and helps you stay on top of things. It plugs into clients like claude, chatGPT, claude code, and codex, and gives them a single source of @context about your work. I use it with claude code to manage product specs. > Your AI tools are users of context, not competitors. @context is built with privacy and security as first principles. It runs in two modes: 1. **Owner mode.** You get every tool. Capture context (*"met Kyle from Agno, follow up next week"*), retrieve context (*"give me a rundown of my day"*), and prepare context (*"process today"*). 2. **Guest mode.** Teammates (*and their agents*) can leave updates in your queue. You get briefed when you ask for a rundown. @context runs on Agno's AgentOS runtime, so user identity is verified on every request, and tools are assigned by role (owner or guest). > Built on [Agno](https://docs.agno.com). ## Job Scope @context has five jobs. 1. **Maintain a CRM.** Share *"met Kyle from Agno, wants a partnership, follow up next week"*, and it stores a contact, a note, and a dated reminder without you picking forms or fields. 2. **Maintain a knowledge base.** @context writes product specs, parses customer interview notes, manages project briefs, and runs deep research, then keeps it all neatly organized in one place. 3. **Run your day, plan your week, prep ahead.** @context runs repeatable playbooks to make things easier. A few come built in, and you should customize them and add your own. Here are the included ones: - **Rundown** *("what's on today?")*: a prioritized brief of things on your plate. One digest instead of five apps: the updates teammates (and their agents) left in your queue, reminders that are due, today's meetings, the emails you missed, and the Slack threads worth a look. - **Week plan** *("what's my week?")*: priorities for the week. Runs Sunday evening and lands in your DMs, so you start the week with 🔥 - **Prep** *("prep for my 2pm with Kyle")*: a tight pre-meeting brief covering who they are, notes, past threads, what's still open, email and Slack exchanges, and public background from the web for contacts you don't know yet. @context runs these playbooks on demand or on a schedule. The daily rundown and weekly plan DM the brief straight to you. 4. **Represent you.** Your teammates (and their agents) can share non-urgent updates with your @context. A teammate types *"@your-context my claude fixed the auth bug"*, and it lands in your queue and surfaces in your next rundown. It works outbound too. Your @context can message people and channels on Slack on your behalf, and @-mention a teammate's @context to drop an update in *their* queue. That's how a team's contexts talk to each other (the [context network](docs/NETWORK.md)). This keeps your signal-to-noise high. 5. **Draft and schedule.** Connect [Gmail and Calendar](docs/GOOGLE.md), and @context reads your real inbox and calendar, drafts your follow-ups straight into Gmail for you to send, and sends calendar changes to your approvals queue. ## Security @context is an alter ego with access to a lot of sensitive information, so the security boundaries need to be AIRTIGHT. Agno's AgentOS makes two things possible: 1. **Verify the user making the request.** AgentOS extracts the `user_id` from the JWT or the Slack request, so we can tell whether the caller is the owner or a guest. 2. **Assign tools by role.** Based on that, we add the right tools to the agent. This model lets us build a system that anyone can write to, but only you can read from or act through. To everyone else, it is a polite notetaker that only captures. Although it does remember who it is talking to: each caller gets their own user-memory, kept entirely separate from yours. External actions are double gated. Changing your calendar (`update_calendar`) pauses for explicit approval before it runs, using AgentOS's `requires_confirmation` and `approval_type="required"` settings. Email goes a step further. `update_gmail` can *only* draft, so the follow-up waits in your Gmail drafts for you to review and send. It never sends on its own. Everything runs locally or in your own cloud, inside your VPC. Every byte of data lives in your own database: the CRM, the knowledge base, and the inbox. Read [`docs/SECURITY.md`](docs/SECURITY.md) for more details. ## Get started > Requires [Docker](https://www.docker.com/get-started/) installed and running. ```sh git clone https://github.com/agno-agi/context.git cd context # Configure credentials cp example.env .env # Open .env: set OPENAI_API_KEY, and set OWNER_ID to the email you sign in to os.agno.com with. # OWNER_NAME is an optional display name, set it as your name. # Run on Docker docker compose up -d --build ``` Confirm it is live at [http://localhost:8000/docs](http://localhost:8000/docs). ## AgentOS UI @context runs on AgentOS, which comes with a web UI for managing and monitoring @context. Use the AgentOS UI to chat with @context, view sessions, approve actions and more. <img width="3066" height="2046" alt="Local Context AgentOS" src="https://github.com/user-attachments/assets/ee4b789a-1612-4b5d-9bd4-37e68ede91c4" /> 1. Open [os.agno.com](https://os.agno.com) and sign in with your email (the same one you set as `OWNER_ID`). 2. Click **Connect AgentOS → Local**. 3. Enter `http://localhost:8000`, name it "Local Context" and connect. 4. Click on the chat button under Context. 5. Try one of the quick prompts. ## MCP server The main way to use @context is from an MCP client like Claude Code, Codex, Claude, Cursor, and ChatGPT. Connect your favorite AI tools to @context's MCP server at `http://localhost:8000/mcp`. > Note: @context's MCP server is **owner-only**, so keep an eye on security. ### Add @context to MCP clients automatically Add @context to every MCP client on your machine with one command: ```sh python scripts/connect.py ``` The script finds Claude Code, Codex, the Claude Desktop app, and Cursor, and registers @context with each. Use `--dry-run` to preview and `--remove` to undo. Once you've deployed, the same script points your clients at the live instance — see [Connect production @context MCP server](#connect-production-context-mcp-server). ### Add @context to MCP clients manually For CLI clients, run the following commands: ```sh claude mcp add -s user --transport http context http://localhost:8000/mcp # Claude Code (user scope) codex mcp add --url http://localhost:8000/mcp context # Codex ``` **Claude Desktop** needs that bridge in `claude_desktop_config.json`, because its "Add custom connector" dialog only accepts `https` URLs. Add this (keep any existing keys) and restart the app: ```json { "mcpServers": { "context": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:8000/mcp", "--transport", "http-only"] } } } ``` **Cursor** speaks remote MCP directly (no bridge). Add this to `~/.cursor/mcp.json` and restart Cursor: ```json { "mcpServers": { "context": { "url": "http://localhost:8000/mcp" } } } ``` See [`docs/MCP.md`](docs/MCP.md) for more details. ## Slack Slack is where @context comes alive. It's the interface where I (@ashpreetbedi) use it the most and the interface that allows your team (and their agents) to talk to @context. To set it up, you need to: 1. Create a Slack app 2. Get the Bot User OAuth Token and Signing Secret 3. Set the environment variables in `.env` or `.env.production` 4. Restart the application Read [`docs/SLACK.md`](docs/SLACK.md) for the Slack setup guide. ## @context Knowledge Base @context comes with a knowledge base that acts as its second brain. @context stores everything from product specs and research notes to "what I know about X" pages in this knowledge base. The knowledge base is stored on the filesystem by default (a gitignored `knowledge/` folder in this repo) but I highly recommend pointing it to a git repo or notion database for production. See [`docs/KNOWLEDGE.md`](docs/KNOWLEDGE.md) for the full guide. Try: - *Write a one-pager on the advantages of building our own agent-platform* - *Write up a decision: we're standardizing on agno* - *What in my knowledge base needs attention?* ## @context CRM @context comes with a CRM that gives it structured memory about people, projects, meetings, reminders, notes and contacts. This auto-managing crm is @context's superpower. Use it to manage projects, meetings, reminders, notes, and contacts. @context maps what you tell it onto the right table - no forms, no fields - and can create new tables on demand. Try: - *"Add Dana Reyes, Head of Platform at Acme, dana@acme.com - and remind me to send her the integration spec next Tuesday."* - *"Who do I know at Acme?"* - *"What reminders do I have coming up?"* - *"Tell me about Northwind."* @context's database lives in the `crm` Postgres schema: writes are confined to that schema and every row is scoped to your `user_id`, so a guest can't see this data. See [`docs/CRM.md`](docs/CRM.md) for the schema, the filing rules, and the write boundary. ## Run in production @context runs anywhere that runs a Docker container. For a quick deployment, the repo includes a script to run on Railway. The `scripts/railway/up.sh` script will run @context as a service with Postgres on the same private network. It reads credentials from `.env.production`, and creates a public domain you connect to in the AgentOS UI. > Requires the [Railway CLI](https://docs.railway.com/cli#installing-the-cli) ### 1. Production env Create the production environment file. ```sh cp .env .env.production ``` The deploy scripts read `.env.production` first and fall back to `.env` if it doesn't exist. ### 2. Deploy Run the `up.sh` script to run @context + postgres on Railway. First, login to Railway. ```sh railway login ``` Then run the `up.sh` script. ```sh ./scripts/railway/up.sh ``` The script will now pause and wait for you to mint the JWT verification key. ### 3. Enable Token Based Authorization Token-Based Authorization is on by default. Without the `JWT_VERIFICATION_KEY` environment variable in `.env.production`, the AgentOS will not serve traffic. That is the safe default for an agent that has access to sensitive information. You can issue and verify your own JWT (see [BYO JWT](https://docs.agno.com/agent-os/security/authorization/self-hosted)) or mint a JWT verification key at [os.agno.com](https://os.agno.com). The `up.sh` script pauses and waits for you to add the JWT verification key to `.env.production`. Here's how you can get one from os.agno.com: 1. Open [os.agno.com](https://os.agno.com), click **Connect AgentOS → Live** 2. The `up.sh` script will print the AgentOS domain, paste it into the input field. 3. Enable **Token Based Authorization** and click **Connect**. 4. Copy the public key and paste it into `.env.production`. 5. Back in the terminal, press Enter. `up.sh` will read the key and deploy the AgentOS service to Railway. ### 4. Verify You can verify the deployment on the Railway dashboard or in the terminal by watching the logs: ```sh railway logs --service agent-os ``` If you add/update any values in `.env.production`, you can sync them to Railway with: ```sh ./scripts/railway/env-sync.sh ``` ### 5. Redeploy after code changes If you make code changes (which you most definitely will), you can redeploy the AgentOS service to Railway with: ```sh ./scripts/railway/redeploy.sh ``` Or enable auto-deploy in the Railway dashboard: 1. Open the Railway dashboard 2. Navigate to the agent-os service 3. Click **Settings** 4. Click **Source** and select the git repo for this project 5. Set the deploy branch to `main` and click **Deploy** ### 6. Point Slack at production If you set Slack up locally, your Slack app's request URLs still point at your local @context via the ngrok tunnel. Repoint the `/slack/events` and `/slack/interactions` request URLs to your Railway domain. AgentOS must already be deployed and serving traffic so Slack's URL re-verification passes. See [`docs/SLACK.md`](docs/SLACK.md#moving-from-local-to-production) for full steps. ## Connect production @context MCP server Once @context is deployed (you have a Railway domain), point your MCP clients at the production endpoint instead of localhost. The deployed server is JWT-gated, so this needs a bearer token — for the MCP server, we mint our own and push it to Railway. One command does the whole thing: ```sh source .venv/bin/activate # mint needs pyjwt + cryptography (in requirements) ./scripts/setup_context.sh # login → mint token → push public key → redeploy → wire clients ``` [`scripts/setup_context.sh`](scripts/setup_context.sh) is the single front door. By default it does a full setup: checks `railway login`, mints a fresh token, pushes the public key, runs a `railway up` redeploy (so a `railway.json` change like `numReplicas` lands), wires Claude Code, Codex, Claude Desktop, and Cursor with the token, then tells you to restart your apps. It never restarts apps for you or touches your data. Re-run it any time to rotate the token — add **`--no-redeploy`** to skip the redeploy and just rotate the token + rewire clients. Under the hood it chains three pieces you can also run by hand: 1. [`scripts/mint_mcp_jwt.py`](scripts/mint_mcp_jwt.py) — self-issues an RS256 keypair (private key stays local in gitignored `secrets/`) and writes the public key + a signed admin token to `.env.production`. 2. [`scripts/railway/env-sync.sh`](scripts/railway/env-sync.sh) — pushes the **public** key to Railway so the deploy trusts your token (the token itself stays off the server). 3. [`scripts/connect.py --production`](scripts/connect.py) — threads the token into Claude Code, Codex, Claude Desktop, and Cursor. You self-issue the token instead of copying one from os.agno.com, and @context trusts your key *alongside* the os.agno.com one — so the [AgentOS UI](#agentos-ui) keeps working too. See [`docs/MCP.md`](docs/MCP.md#self-issued-production-token) for the full details: where the token comes from, per-client specifics (Codex's `$CONTEXT_JWT`, switching local→prod), ChatGPT/Claude web, and how it's secured. ## Connect @context knowledge base to Git When testing locally we can use the local `knowledge/` folder to store the knowledge base. But in production we need to back the knowledge base with a durable solution like a Git repo. Here's how to connect @context's knowledge base to a Git repo. 1. Open [github.com/new](https://github.com/new) and create a new repo for your @context's knowledge base. - Name: `your-username/your-context` - Visibility: Mark the repo as private. - Add README: Yes 2. Mint a GitHub token with push access to the repo. - Open [github.com/settings/personal-access-tokens](https://github.com/settings/personal-access-tokens) and create a new fine-grained token. - Click on **Generate new token** - Name: `Your Context` - Expiration: **No expiration** - Repository access: **Only select repositories** and select the repo you created in step 1. - **Add Permissions** -> **Select Contents** - Remember to update Access to **read and write** - Generate token and copy the token. 3. Add both to `.env.production`: ```sh KNOWLEDGE_REPO_URL=https://github.com/you/your-specs.git KNOWLEDGE_GITHUB_TOKEN=ghp_... ``` 4. Sync to Railway: ```sh ./scripts/railway/env-sync.sh ``` See [`docs/KNOWLEDGE.md`](docs/KNOWLEDGE.md) for the full guide. ## Connect Gmail and Calendar You can connect your Gmail and Calendar to @context to ground the rundown and meeting prep in your real inbox and calendar. See [`docs/GOOGLE.md`](docs/GOOGLE.md) for more details. ## Understanding the codebase @context has three main components. Review them in order. ### The app (`app/`) @context is a FastAPI application running the AgentOS runtime. [`app/main.py`](app/main.py) is the entrypoint and [`app/settings.py`](app/settings.py) holds shared settings. [`app/identity.py`](app/identity.py) is where identity is validated. It looks dense, but all it does is check whether `user_id` is in the `OWNER_ID` list (comma-separated). [`app/mcp.py`](app/mcp.py) is the owner-only MCP server — one tool (`use_context`) that lets you read, act, and file through @context from the Claude/ChatGPT desktop apps and CLI clients (see [MCP server](#mcp-server)). ### The agents (`agents/`) The main agent is [`agents/context.py`](agents/context.py). `context_tools()` adds tools to the agent based on the caller's role, and `caller_information()` adds the matching instructions. The supporting files: - [`agents/instructions.py`](agents/instructions.py) defines the role-specific instructions. - [`agents/sources.py`](agents/sources.py) defines the context providers (crm, knowledge, workspace, web, Slack, Gmail, Calendar) and how each registers its `query_` / `update_` tools. - [`agents/inbox.py`](agents/inbox.py) defines the inbound queue: `submit_update` (anyone), then `rundown` / `acknowledge` (you only). - [`agents/policy.py`](agents/policy.py) defines the pre-hook and tool-hook that back the owner/guest boundary. - [`workflows/`](workflows/) defines the runnable `Workflow` objects (the reminder sweep, the digests) and `dm_owner`; [`app/schedules.py`](app/schedules.py) registers their crons. The reminder sweep (`workflows/reminders.py`) files due reminders into the inbound queue, run hourly by the `queue-reminders` schedule. ### 技能（`skills/`） 本仓库包含 **两种不同的技能**。请保持它们分开。 - **运行时技能**（[`skills/`](skills/)）是部署的 `@context` 代理为其所有者运行的剧本，通过自然语言调用（例如“计划我的周”）并由所有者控制。您可以根据需要添加自己的技能。 - **编码代理工作流**（[`.agents/skills/`](.agents/skills/)）是编码代理（Claude Code、Codex等）在开发此仓库时运行的 `/slash-command` 工作流。它们在[使用编码代理](AGENTS.md#使用编码代理)中涵盖。 以下是仓库中包含的运行时技能： - [`skills/week-plan/SKILL.md`](skills/week-plan/SKILL.md)。 - [`skills/daily-rundown/SKILL.md`](skills/daily-rundown/SKILL.md)。 - [`skills/prep-for/SKILL.md`](skills/prep-for/SKILL.md)。 - [`skills/process-today/SKILL.md`](skills/process-today/SKILL.md)。 - [`skills/research/SKILL.md`](skills/research/SKILL.md)。 - [`skills/knowledge-review/SKILL.md`](skills/knowledge-review/SKILL.md)。 ## 评估 `@context` 带有用于回归测试的评估套件（[`evals/`](evals/)）。它测试以下声明：*任何人都可以编写，只有您可以读取。* 运行它： ```sh python -m evals # 运行完整套件 python -m evals -v # 流式传输完整的代理运行 python -m evals --case <name> # 运行单个测试用例 ``` ## 环境变量 | 变量名 | 是否必需 | 默认值 | 描述 | | --- | --- | --- | --- | | `OPENAI_API_KEY` | 是 | 无 | 用于模型和嵌入的OpenAI密钥。 | | `OWNER_ID` | 生产环境必填 | 无 | 以逗号分隔的身份标识，视为所有者（JWT `sub` 和/或Slack邮箱）。第一个是规范身份标识。未设置意味着所有人都是捕获对象。 | | `OWNER_NAME` | 否 | 规范 `OWNER_ID` | 显示名称，渲染到提示中。仅用于美观，从不作为身份标识匹配。 | | `RUNTIME_ENV` | 否 | `prd` | `dev` 启用热重载并禁用JWT。Compose设置为 `dev` 以适应本地开发。 | | `JWT_VERIFICATION_KEY` | 生产环境必填 | 无 | 来自 os.agno.com 的公钥。当 `RUNTIME_ENV=prd` 时必填。 | | `CONTEXT_SELF_VERIFICATION_KEY` | 否 | 无 | 应用程序信任的第二个JWT公钥，与os.agno.com密钥相同 — 您自己的密钥，以便您颁发的令牌通过 `scripts/mint_mcp_jwt.py` 验证（os.agno.com UI保持正常工作）。由该脚本编写；通过 `env-sync.sh` 推送到服务器。参见[连接生产 `@context` MCP服务器](#连接生产-context-mcp服务器)。 | | `CONTEXT_MCP_JWT` | 否 | 无 | 自颁发的承载令牌，`scripts/connect.py --production` 将其线程到您的MCP客户端。仅限客户端（存在于 `.env.production` 中，从不推送到服务器）。由 `scripts/mint_mcp_jwt.py` 铸造。 | | `AGENTOS_URL` | 否 | `http://127.0.0.1:8000` | 调度器基准URL。同时锚定MCP服务器的Host允许列表 — 将其设置为您的 Railway/ngrok域名，以便部署或隧道的 `/mcp` 端点接受该Host（参见 [`docs/MCP.md`](docs/MCP.md)）。 | | `INTERNAL_SERVICE_TOKEN` | 否 | 自动生成 | 调度器到OS的身份验证令牌。部署仅发送1个副本，因此自动生成的令牌足够；`scripts/railway/up.sh` 仍然固定一个，以便扩展保持正确（在 `.env.production` 中覆盖）。参见 [`docs/SCALING.md`](docs/SCALING.md) 。 | | `PARALLEL_API_KEY` | 否 | 无 | 将 `web` 源从无密钥Parallel MCP切换到身份验证SDK（更高的速率上限）；建议用于生产。在 [platform.parallel.ai](https://platform.parallel.ai/settings?tab=api-keys) 获取密钥。 | | `SLACK_BOT_TOKEN` / `SLACK_SIGNING_SECRET` | 否 | 无 | 两者都启用Slack接口。仅限机器人令牌激活 `slack` 源（`query_slack` +无门控 `update_slack` 发送工具）并自动启用定时摘要。参见 [`docs/SLACK.md`](docs/SLACK.md) 。 | | `DAILY_DIGEST_CRON` / `WEEKLY_DIGEST_CRON` | 否 | `0 13 * * *` / `0 22 * * 0` | 用于Slack交付的每日总结和每周计划的UTC cron（仅当设置Slack时启用）。参见 [`docs/SLACK.md`](docs/SLACK.md) 。 | | `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` / `GOOGLE_PROJECT_ID` | 否 | 无 | 连接您的Gmail + 日历；使用 `python scripts/google_mint_tokens.py` 铸造令牌。参见 [`docs/GOOGLE.md`](docs/GOOGLE.md) 。 | | `GMAIL_TOKEN_JSON_B64` / `CALENDAR_TOKEN_JSON_B64` | 否 | 无 | 经过base64编码的Gmail/日历令牌，以便它们在部署后存活。入口点在启动时恢复它们。参见 [`docs/GOOGLE.md`](docs/GOOGLE.md) 。 | | `KNOWLEDGE_REPO_URL` / `KNOWLEDGE_GITHUB_TOKEN` | 否 | 无 | 设置两者以使用Git仓库而非本地文件支持 `knowledge` 基础。 可选参数： `KNOWLEDGE_BRANCH` （默认为 `main`），`KNOWLEDGE_LOCAL_PATH`。 | | `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASS` / `DB_DATABASE` | 否 | 匹配docker-compose | Postgres连接。 | | `DB_DRIVER` | 否 | `postgresql+psycopg` | SQLAlchemy驱动程序。 | | `AGNO_DEBUG` | 否 | `False` | 如果为 `True`，Agno将发出详细的调试日志。Compose为开发环境设置此参数。 | | `WAIT_FOR_DB` | 否 | `False` | 如果为 `True`，入口点将在启动前等待数据库。Compose设置此参数。 | ## 了解更多 - [`AGENTS.md`](AGENTS.md)：架构和约定（编码代理的真实来源）。 - [Agno文档](https://docs.agno.com) - [AgentOS介绍](https://docs.agno.com/agent-os/introduction) - [GitHub上的Agno](https://github.com/agno-agi/agno) （如果这很有用，请给它一个星标）。