> ## Documentation Index > Fetch the complete documentation index at: https://agno-v2-codex-docs-audit-20260719-0149.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Context > Self-hosted context manager that organizes your work into a private CRM and knowledge base your AI tools share over MCP. **@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, Codex, and Cursor, and gives them a single source of context about your work. Anyone can write to your context. Only you can read it or act through it. @context is an [App](/deploy/introduction): a complete agent product you fork, run on your own infrastructure, and adapt. See the [repo](https://github.com/agno-agi/context) for the source. ## How it works @context is one Agno agent that captures, files, and retrieves your working context across many sources. In production, AgentOS verifies HTTP identities from JWTs. Slack verifies signed events and maps their authors to user IDs. Local HTTP requests trust the caller-supplied `user_id`, so run them only on a trusted machine. @context assigns tools from that identity: 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 and check their own submissions. When Calendar is configured, they can also ask `owner_availability` for your open windows. It returns free/busy intervals without event details. You get briefed when you ask for a rundown. ### Five jobs 1. **Maintain a CRM.** Share *"met Kyle from Agno, wants a partnership, follow up next week"*, and @context 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 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. 4. **Represent you.** 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. @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](https://github.com/agno-agi/context/blob/main/docs/NETWORK.md)). 5. **Draft and schedule.** Connect Gmail and Calendar, 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. The built-in playbooks: | Playbook | Ask | What you get | | ------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Rundown** | "What's on today?" | One digest instead of five apps: the updates teammates 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. When Slack is configured, runs Sunday evening and lands in your Slack DMs | | **Prep** | "Prep for my 2pm with Kyle" | A pre-meeting brief: who they are, notes, past threads, what's still open, and public background for contacts you don't know yet | @context runs these on demand. When Slack is configured, the scheduled daily rundown and weekly plan DM the brief straight to you. Playbooks live in `skills/`, one `SKILL.md` per folder, alongside `process-today`, `research`, and `knowledge-review`. ### Context sources Most sources are sub-agents behind at most two tools: `query_` to read and `update_` to write. The workspace source is the exception; it exposes its read tools (`list_files`, `search_content`, `read_file`) directly to the agent. | Source | Access | Enabled by | | ----------- | ----------------------------------------- | ---------------------- | | `crm` | Read and write | Always on | | `knowledge` | Read and write | Always on | | `workspace` | Read | Always on | | `web` | Read | Always on | | `slack` | Read and write | `SLACK_BOT_TOKEN` | | `gmail` | Read and write; writes are drafts only | `GOOGLE_*` credentials | | `calendar` | Read and write; writes pause for approval | `GOOGLE_*` credentials | The `crm` source is the structured store: contacts, projects, meetings, reminders, notes, and queued updates in the `crm` Postgres schema. Agent instructions require CRM writes to use that schema and stamp rows with `user_id`. A heuristic SQL guard blocks common writes to other schemas, but the database connection does not use a least-privilege role or row-level security. Guest privacy is enforced separately by the code-selected guest toolset, which exposes no CRM query tool. The `knowledge` source is the prose store for specs and research notes. It lives on the filesystem by default and can use a private Git repository in production. ### Security @context handles sensitive information. The toolset is chosen in code from the request identity before the model runs. Production HTTP requests use verified JWT identities, and Slack events use signed author identities. Local HTTP development trusts the caller-supplied identity. The owner gets the full surface. A guest gets `submit_update` to append to your queue, `my_updates` to see only their own submissions, and `owner_availability` when Calendar is configured. The availability tool returns free/busy intervals without event details. The guest toolset cannot access your CRM, knowledge base, inbox, or calendar events. Each caller gets separate user memory. The Slack, Calendar, and Gmail write tools are owner-only. `update_slack` sends messages immediately. `update_calendar` pauses for your explicit approval before it changes the calendar. `update_gmail` creates a draft for you to review and send. It never sends email. @context runs locally or in your own cloud. Its CRM and inbound queue live in Postgres. Its knowledge base lives on the filesystem by default and can use a private Git repository in production. Slack, Gmail, Calendar, and web are external sources accessed through provider APIs. See [docs/SECURITY.md](https://github.com/agno-agi/context/blob/main/docs/SECURITY.md). ## Run locally **Prerequisites:** [Docker](https://www.docker.com/get-started/) installed and running. An [OpenAI API key](https://platform.openai.com). ```bash theme={null} git clone https://github.com/agno-agi/context.git cd context 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 docker compose up -d --build ``` Confirm it is live at [localhost:8000/docs](http://localhost:8000/docs). `OWNER_ID` decides who counts as the owner. Set it to your email; anyone else gets the capture-only guest tools. `OWNER_NAME` is an optional display name. ### Connect the AgentOS UI AgentOS comes with a web UI for managing and monitoring @context. Use it to chat with @context, view sessions, and approve actions. 1. Open [os.agno.com](https://os.agno.com) and sign in with the email you set as `OWNER_ID`. 2. Click **Connect AgentOS** → **Local**, enter `http://localhost:8000`, and name it **Local Context**. 3. Open the chat under Context and try one of the quick prompts. ### Connect MCP clients The main way to use @context is from an MCP client like Claude Code, Codex, Claude, Cursor, or ChatGPT. The local server runs at `http://localhost:8000/mcp` with keyless-as-owner access. With `OWNER_ID` configured, every client that can reach the endpoint is treated as that owner and receives the full read, write, and action surface. Keep the development endpoint on a trusted machine. One command adds @context to every MCP client on your machine: ```bash theme={null} python scripts/connect.py ``` The script finds Claude Code, Codex, Claude Desktop, and Cursor, and registers @context with each. Use `--dry-run` to preview and `--remove` to undo. To register the CLI clients by hand: ```bash theme={null} claude mcp add -s user --transport http context http://localhost:8000/mcp codex mcp add --url http://localhost:8000/mcp context ``` Claude Desktop and Cursor take config-file entries. See [docs/MCP.md](https://github.com/agno-agi/context/blob/main/docs/MCP.md) for both. ## Deploy to Railway @context runs anywhere that runs a Docker container. For a quick deployment, `scripts/railway/up.sh` runs @context and Postgres on the same private network. It reads credentials from `.env.production` and creates the public domain you connect to in the AgentOS UI. **Prerequisites:** [Railway CLI](https://docs.railway.com/cli#installing-the-cli) installed and `railway login` completed. ```bash theme={null} cp .env .env.production ``` The deploy scripts read `.env.production` first and fall back to `.env`. ```bash theme={null} ./scripts/railway/up.sh ``` The script creates your public domain, then pauses and waits while you mint the JWT verification key. Token-Based Authorization is on by default. Without a `JWT_VERIFICATION_KEY` in `.env.production`, the AgentOS will not serve traffic. That is the safe default for an agent that holds your work context. You can also [issue and verify your own JWT](/agent-os/security/authorization/self-hosted). 1. Open [os.agno.com](https://os.agno.com), click **Connect AgentOS** → **Live**, and paste the domain the script printed. 2. Turn on **Token-Based Authorization** and click **Connect**. 3. Copy the public key into `.env.production` as `JWT_VERIFICATION_KEY`. 4. Back in the terminal, press Enter. The script reads the key and deploys the service. ```bash theme={null} railway logs --service agent-os ``` Open `https:///docs` to confirm the API is serving. If you add or update values in `.env.production`, sync them with `./scripts/railway/env-sync.sh`. After code changes, redeploy with `./scripts/railway/redeploy.sh`, or connect the repo in the Railway dashboard to auto-deploy on push. ### Point MCP clients at production Production connections ride MCP OAuth. Setting `MCP_CONNECT_SECRET` turns the deployment into its own OAuth 2.1 authorization server on `/mcp`: a client connects by URL, and you approve it once on a consent page by typing the secret. `up.sh` already generated the secret on deploy. If you deployed before it existed, one command arms everything: ```bash theme={null} ./scripts/setup_context.sh ``` `setup_context.sh` makes sure `MCP_CONNECT_SECRET` and `AGENTOS_MCP_SIGNING_KEY` exist in `.env.production` (generating them when missing), syncs the env to Railway, runs an explicit code and image redeploy, and prints the connector recipe with your real domain and secret. Add `--no-redeploy` to skip the explicit `railway up` redeploy. Environment sync can still trigger a Railway redeploy when it pushes changed variables. Then connect your clients. In claude.ai or ChatGPT, add `https:///mcp` as a custom connector, leave the OAuth client ID and secret fields empty, and approve the consent page with the secret. For the CLI clients, `uvx agno connect --url https://` wires Claude Code, Codex, Cursor, and Claude Desktop and prints each client's sign-in step. The AgentOS UI keeps working alongside; it authenticates with the os.agno.com JWT, a separate door from MCP OAuth. Rotating `AGENTOS_MCP_SIGNING_KEY` revokes every issued token, and rotating `MCP_CONNECT_SECRET` only gates future consents. See [docs/MCP.md](https://github.com/agno-agi/context/blob/main/docs/MCP.md#production-mcp-oauth) for the consent flow, per-client specifics, and ChatGPT and Claude on the web. ### Back the knowledge base with Git Local runs store the knowledge base in a gitignored `knowledge/` folder. In production, back it with a private Git repo: create one, mint a fine-grained token with read and write access to its contents, and add both to `.env.production`: ```bash theme={null} KNOWLEDGE_REPO_URL=https://github.com/you/your-context.git KNOWLEDGE_GITHUB_TOKEN=ghp_... ``` Then sync with `./scripts/railway/env-sync.sh`. Every update commits and pushes, so the git history is your audit trail. See [docs/KNOWLEDGE.md](https://github.com/agno-agi/context/blob/main/docs/KNOWLEDGE.md). ## Connect to Slack With Slack configured, teammates can @-mention @context to leave you updates, you can DM it for private conversations, and the scheduled daily rundown and weekly plan land in your DMs. 1. Create a Slack app from the manifest in [docs/SLACK.md](https://github.com/agno-agi/context/blob/main/docs/SLACK.md). 2. Copy the Bot User OAuth Token and Signing Secret. 3. Set `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` in `.env` or `.env.production`. 4. Restart the application. Local runs need a public URL for Slack's callbacks, so use an ngrok tunnel. Once you deploy, repoint the app's `/slack/events` and `/slack/interactions` request URLs at your Railway domain. ## Connect Gmail and Calendar Connect Gmail and Calendar to ground the rundown and meeting prep in your real inbox and calendar. Set `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, and `GOOGLE_PROJECT_ID`, then mint the consent tokens once with `python scripts/google_mint_tokens.py`. See [docs/GOOGLE.md](https://github.com/agno-agi/context/blob/main/docs/GOOGLE.md). ## Example prompts Try these from the AgentOS UI, Slack, or an MCP client: * Add Dana Reyes, Head of Platform at Acme, [dana@acme.com](mailto:dana@acme.com). Remind me to send her the integration spec next Tuesday. * Who do I know at Acme? * What's on today? * Prep for my 2pm with Kyle * Write up a decision: we're standardizing on Agno * What in my knowledge base needs attention? ## Run evals @context comes with an eval suite ([`evals/`](https://github.com/agno-agi/context/tree/main/evals)) for regression testing the security model. It tests the claim that anyone can write and only you can read: deterministic gates check that a guest's toolset stays capture-only and the MCP server stays owner-only, and an adversarial guest arc tries to break the boundary. ```bash theme={null} python -m evals # run the full suite python -m evals -v # stream the full agent run python -m evals --case # one case ``` ## Source The [GitHub repo](https://github.com/agno-agi/context) has the full detail: | Guide | Covers | | -------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | [`AGENTS.md`](https://github.com/agno-agi/context/blob/main/AGENTS.md) | Architecture, key files, and conventions for coding agents | | [`docs/SECURITY.md`](https://github.com/agno-agi/context/blob/main/docs/SECURITY.md) | The owner/guest model, act tools, and the approval gate | | [`docs/MCP.md`](https://github.com/agno-agi/context/blob/main/docs/MCP.md) | Per-client MCP setup and production MCP OAuth | | [`docs/SLACK.md`](https://github.com/agno-agi/context/blob/main/docs/SLACK.md) | The app manifest, identity resolution, and moving to production | | [`docs/KNOWLEDGE.md`](https://github.com/agno-agi/context/blob/main/docs/KNOWLEDGE.md) | The knowledge base and Git backing | | [`docs/CRM.md`](https://github.com/agno-agi/context/blob/main/docs/CRM.md) | The `crm` schema, filing rules, and the write boundary | | [`docs/GOOGLE.md`](https://github.com/agno-agi/context/blob/main/docs/GOOGLE.md) | Gmail and Calendar setup | | [`docs/NETWORK.md`](https://github.com/agno-agi/context/blob/main/docs/NETWORK.md) | How a team's contexts talk to each other |