Coding agents forget decisions between sessions. OpenContext MCP exposes a lightweight Model Context Protocol server that enables AI agents to read and write durable .opencontext/
markdown rules.
.opencontext/
├── architecture.md
├── api-contracts.md
└── coding_rules.md
01# Architecture0203## Authentication0405We use **JWT with refresh tokens**.0607### Access Token08- 15-minute expiry09- Stored in memory only1011### Refresh Token12- 7-day expiry13- HttpOnly secure cookie14- Rotated on each use
Without vs. With OpenContext #
AI agents are powerful — but only if they remember what matters.
Without Memory
Session context vanishes
Agents lose all memory of prior decisions, conventions, and architecture between sessions.
Architectural rules get broken
Without persistent rules, agents re-implement patterns that conflict with your codebase.
Agents re-ask conventions
"Should I use Zod or Yup?" — the same question, every session, no memory of past answers.
With OpenContext
Plain .md storage in your repo
Plain markdown files that persist across every session. Agents read before acting.
Zero cloud or account lock-in
Open any .opencontext/ file in your editor. Human-readable, machine-readable, no magic.
Team-wide alignment via Git
Commit shared rules to your repo, or .gitignore for private local context. Your choice.
Get Started in 3 Steps #
Go from zero-install setup to a codebase with durable, searchable memory in one guided workflow.
Step 01
Add OpenContext to your MCP Client
Add the OpenContext MCP entry to your client configuration. No global install is required. Your client launches the server via npx
over stdio
.
Core command
["npx", "-y", "opencontext-mcp"]
Config path
opencode.json / project MCP settings
{
"mcp": {
"opencontext": {
"type": "local",
"command": ["npx", "-y", "opencontext-mcp"],
"enabled": true
}
}
}
Two Lightweight MCP Tools #
Minimal surface area. Maximum utility. Every tool your agent needs.
save_context
Persists a markdown context entry under .opencontext/ with the given topic name. Auto-creates the directory if it doesn't exist. Overwrites existing files with the same topic name.
topic
stringTopic name used as the filename. Use kebab-case or snake_case (e.g. "architecture" creates architecture.md).
content
stringFull markdown content to write. Supports headers, lists, code blocks, and all standard markdown.
read_context
Reads a specific topic file or discovers all available topics when called without arguments. Returns raw markdown content.
topic
string (optional)Topic name to retrieve. Omit entirely to list all available topic filenames.
Agent Workflows & Ready Prompts #
OpenContext becomes useful when your agents are explicitly told when to read and write durable memory. Drop these prompts into your planning and implementation workflows.
Always use read_context before modifying code. Use save_context when establishing durable rules or API contracts.
Git Strategy #
Choose whether OpenContext becomes shared project memory or a purely local working layer.
Shared Team Memory
git add .opencontext
Commit plain markdown rules to the repository so architecture decisions, API contracts, and coding conventions stay visible to the whole team and can be reviewed in CI.
Local Private Notes
.opencontext/
Keep scratchpads, debugging notes, and developer-specific rules local by adding the directory to .gitignore. The workflow stays transparent without sharing personal context.