gcontext-ai 0.2.2

gcontext — file-based knowledge protocol for AI agents

gcontext

Context engineering for AI agents.

Build context like you build code: modular, version-controlled, composable.

---

The problem

AI agents fail for the same reason large codebases fail: implicit state.

Prompts become undocumented architecture. Instructions drift between conversations. Context duplicates across files. Memory becomes unreliable. Every session starts with "let me remind you how our deploy works."

This isn't a model problem. It's an engineering problem.

Most teams solve it by writing longer prompts, pasting more docs, or hoping the agent remembers. That works until it doesn't, and it stops working fast.

gcontext treats context as infrastructure.

---

Before and after

Without structured context:

• Giant system prompts nobody maintains
• Copy-pasted docs that go stale
• "Remember, our Stripe webhook is at..." every session
• Agent hallucinates because it can't find what it needs
• Context bloat kills quality on long tasks
• Tribal knowledge lives in one person's prompt history

With gcontext:

modules-repo/
  stripe/            → API keys, webhooks, how to query invoices
  postgres/          → schema, migrations, connection details
  deploy-pipeline/   → step-by-step release to production
  bug-triage/        → how to investigate and classify issues

Each module is a self-contained unit of context. Load what the task needs, unload what it doesn't. The agent navigates to what's relevant. Nothing else enters the window.

---

Install

curl -LsSf https://gcontext.ai/gcontext/install.sh | sh

Alternative methods

# Via uv (PyPI name is gcontext-ai; the command is `gcontext`)
uv tool install gcontext-ai

# Via pip
pip install gcontext-ai

Quick start

1. Initialize your workspace

$ gcontext init

Created modules-repo/
Created context/
Ready. Create your first module with: gcontext new integration <name>

This gives you:

.gitignore           # ignores .env
AGENTS.md            # points coding agents at context/system.md (managed block)
context/             # what the agent reads: llms.txt, system.md, principles.md, ...
modules-repo/        # where modules live (seeded with an example/ module)

Re-running gcontext init in an existing workspace errors with "workspace already initialized" — it never overwrites your files.

2. Add an integration

$ claude → "Add a postgres integration"

Creating modules-repo/postgres/
  info.md        ← context about the integration
  llms.txt       ← navigation for the agent
  module.yaml    ← secrets: [PG_URL]
✓ Module created. Requires PG_URL to populate.

Modules live in modules-repo/; gcontext load postgres symlinks one into context/postgres so the agent can navigate to it.

3. Provide the secret it needs

# Add PG_URL to your .env file
echo "PG_URL=postgres://..." >> .env

4. The agent fills in the context

$ claude → "Explore the postgres integration and add the info to modules-repo/postgres/info.md"

Connecting with PG_URL...
  Found 12 tables, 47 columns, 8 relationships
  Writing schema to info.md
✓ Module ready. Agent knows your database.

5. Query your data, add context anytime

$ claude → "How many users signed up this week?"

Reads info.md → already knows users table has created_at
47 users. Free: 31, Pro: 12, Enterprise: 4

Need more context? The agent can add new modules anytime.

---

How it works: composable context

gcontext introduces one core mechanic: composable context.

Modules are independent units of knowledge: an API integration, a deployment procedure, a bug investigation. Each contains plain markdown and a navigation index (llms.txt) the agent uses to find what it needs.

agent reads system.md
  └─ follows llms.txt index
       ├─ stripe/llms.txt    → "here's how Stripe works here"
       ├─ postgres/llms.txt  → "here's the database"
       └─ deploy/llms.txt    → "here's how to ship"
            └─ steps.md      → the actual procedure

Navigation, not retrieval. The agent walks a knowledge tree. It doesn't search a vector space. Deterministic, inspectable, reproducible.

You version-control your code. You version-control your docs. Now version-control what your AI agent knows.

Module kinds

Kind	What it captures	Lifecycle	Example
Integration	How to use an external service, API, or database	Permanent: lives as long as the service does	Stripe, Postgres, GitHub, Slack
Workflow	A repeatable procedure that improves over time	Long-lived: gets better with each run	Deploy to prod, triage bugs, onboard a teammate
Task	A bounded piece of work with progress tracking	Disposable: done when the work is done	Fix billing bug, migrate auth, ship feature X

Different shapes for different lifecycles. They coexist and compose.

---

Real workflows

Software engineering team

modules-repo/
  postgres/          → schema, connection, query patterns
  github/            → repo structure, PR conventions, CI
  deploy-pipeline/   → release steps, rollback procedures
  fix-billing-bug/   → task: reproduce, investigate, fix, verify

The agent reads the database schema, understands CI, follows the deploy playbook, and tracks progress on the billing fix, all from structured context.

Support automation

modules-repo/
  zendesk/           → API access, ticket categories, macros
  stripe/            → subscription lookup, refund procedures
  knowledge-base/    → product docs, known issues, FAQ
  escalation/        → workflow: when and how to escalate

An agent triaging tickets reads the Zendesk integration, checks Stripe for billing context, references the KB, and follows escalation rules, without a 10,000-token system prompt.

Content pipeline

modules-repo/
  cms/               → API, content models, publishing flow
  brand-voice/       → tone guidelines, examples, anti-patterns
  analytics/         → what performs, audience segments
  weekly-newsletter/ → task: this week's edition

Claude Code / Cursor workflow

modules-repo/
  codebase/          → architecture, conventions, key paths
  cloudflare/        → DNS, workers, deployment targets
  monitoring/        → Grafana dashboards, alert rules
  ship-v2-auth/      → task: migrate auth with progress tracking

Point your coding agent at the workspace. It navigates to the module it needs per task: your codebase conventions when writing code, your deploy integration when shipping, your monitoring setup when debugging production.

---

What gcontext is not

gcontext is not:

• A vector database. No embeddings. The agent navigates a file tree, not a similarity search.
• A memory model. No implicit memory. Context is explicit, human-curated, version-controlled.
• A replacement for RAG. Complementary. gcontext structures the knowledge RAG can retrieve from.
• An autonomous agent framework. No agent runtime. Works with the agent you already use.
• Another orchestration layer. No workflow engine. Just structured, navigable knowledge.

gcontext is a context engineering toolkit. It gives your agent a composable knowledge base it can navigate itself.

---

Why the filesystem

"Why not just use a vector database / memory layer?"

	Filesystem (gcontext)	Vector DB / Memory
Version control	git diff, git blame, full history	Requires custom versioning
Inspectability	Open a folder, read the files	Query an API, decode embeddings
Determinism	Same files = same context, every time	Similarity search varies
Human readability	It's markdown	It's vectors
Composability	Load/unload modules like imports	Rebuild index on every change
Tooling	Works with every editor, CI, linter	Needs specialized tooling
Portability	Copy the folder	Export, migrate, re-index

The filesystem is the most universal, inspectable, composable storage layer that exists. Your agent's context should be as maintainable as the code it operates on.

---

Commands

Command	What it does
gcontext init	Create a new workspace (errors if one already exists)
gcontext new <kind> <name> [summary]	Scaffold a module
gcontext load <name> [...]	Activate modules in the workspace
gcontext unload <name>	Deactivate a module
gcontext ls	List all modules and their status
gcontext env	Check if required secrets are set
gcontext validate [name]	Verify module structure

Works with everything

gcontext produces plain markdown files with a navigable index. Any AI that reads files can use it:

Claude Code, Cursor, Windsurf, Copilot, ChatGPT, Codex. If it reads files, it reads gcontext.

Secrets

Modules can declare required environment variables. Values go in .env (gitignored). Run gcontext env to check what's missing.

gcontext Cloud

For a web UI with built-in AI chat, visual module editor, secrets management, and more, see gcontext Cloud.

---

Built by Bleak AI | gcontext.ai