@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.

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). This keeps your signal-to-noise high.

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.

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 for more details.

Get started

Requires Docker installed and running.

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.

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.

1. Open 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:

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.

Add @context to MCP clients manually

For CLI clients, run the following commands:

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:

{
  "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:

{
  "mcpServers": {
    "context": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

See 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 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 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, [email protected] - 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 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

1. Production env

Create the production environment file.

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.

railway login

Then run the up.sh script.

./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) or mint a JWT verification key at 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, 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:

railway logs --service agent-os

If you add/update any values in .env.production, you can sync them to Railway with:

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

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

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 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 — 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 — pushes the public key to Railway so the deploy trusts your token (the token itself stays off the server).
3. scripts/connect.py --production — 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 keeps working too.

See docs/MCP.md 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 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 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:

   KNOWLEDGE_REPO_URL=https://github.com/you/your-specs.git
   KNOWLEDGE_GITHUB_TOKEN=ghp_...
   

4. Sync to Railway:

   ./scripts/railway/env-sync.sh
   

See 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 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 is the entrypoint and app/settings.py holds shared settings. 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 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).

The agents (agents/)

The main agent is 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 defines the role-specific instructions.
• 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 defines the inbound queue: submit_update (anyone), then rundown / acknowledge (you only).
• agents/policy.py defines the pre-hook and tool-hook that back the owner/guest boundary.
• workflows/ defines the runnable Workflow objects (the reminder sweep, the digests) and dm_owner; 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.

The skills (skills/)

The repo has two distinct kinds of skill. Keep them separate.

• Runtime skills (skills/) are playbooks the deployed @context agent runs for its owner, invoked in natural language ("plan my week") and owner-gated. Add your own as needed.
• Coding-agent workflows (.agents/skills/) are /slash-command workflows your coding agent (Claude Code, Codex, others) runs while developing this repo. They are covered under Working with coding agents.

Here are the runtime skills that are included in the repo:

• skills/week-plan/SKILL.md.
• skills/daily-rundown/SKILL.md.
• skills/prep-for/SKILL.md.
• skills/process-today/SKILL.md.
• skills/research/SKILL.md.
• skills/knowledge-review/SKILL.md.

Evals

@context comes with an eval suite (evals/) for regression testing. It's tests the claim that: anyone can write, only you can read.

Run it:

python -m evals                # run the full suite
python -m evals -v             # stream the full agent run
python -m evals --case <name>  # one case

Environment variables

Learn more

• AGENTS.md: architecture and conventions (source of truth for coding agents).
• Agno documentation
• AgentOS introduction
• Agno on GitHub (drop a star if this is useful).