Persistent, project-local memory for AI coding agents.
Most coding agents lose critical decisions between sessions: architecture invariants, API contracts, rejected patterns, and setup quirks. OpenContext solves context loss through a lightweight Model Context Protocol (MCP) server that lets agents read and mutate durable markdown files inside .opencontext/.
No vector databases, no cloud subscriptions, and no hidden state. Memory is plain markdown tracked directly in Git.
Quickstart
Run the MCP server directly without installation via npx:```bash
npx -y opencontext-mcp
### One-Command Setup
Scaffold OpenContext in the current project interactively:```bash
npx -y opencontext-mcp init
init walks you through the setup (enabling OpenCode and Claude Code integration) and generates everything you need:
.opencontext/— directory that holds your context topic files.opencontext.json— configuration templateopencode.json— MCP server entry for OpenCode.mcp.json— MCP server entry for Claude CodeAGENTS.md/CLAUDE.md— workflow reminders for your agents
The init command takes no arguments: it always runs in the current directory, prompts interactively, and never overwrites an existing config.
Client Setup
OpenCode
Add OpenContext to your project MCP configuration (opencode.json) — or let opencontext-mcp init do it for you:```json
{
"mcp": {
"opencontext": {
"type": "local",
"command": ["npx", "-y", "opencontext-mcp"],
"enabled": true
}
}
}
#### Cursor / Claude Desktop / Windsurf
Add OpenContext to your MCP settings file (`claude_desktop_config.json` or Cursor MCP settings):```json
{
"mcpServers": {
"opencontext": {
"command": "npx",
"args": ["-y", "opencontext-mcp"]
}
}
}
Remote Access (HTTP)
Expose the MCP server over the network with the Streamable HTTP transport. The endpoint URL is printed to stderr on startup.```bash
Plain HTTP on 127.0.0.1:3032 (default)
opencontext-mcp --http
Custom port / bind to all interfaces
opencontext-mcp server --http --port 8787 --host 0.0.0.0
The server listens at `http://:/mcp` (stateless Streamable HTTP — one request at a time, no sessions). `GET /` returns basic server info, handy for a browser health check.
---
### Core Tools
| Tool | Parameters | Description |
| --- | --- | --- |
| `read_context` | `topic?` *(optional string)* | Reads a specific context topic, or returns the lightweight topic index (~100 tokens) if omitted. |
| `save_context` | `topic` *(string)*, `content` *(string)* | Writes or mutates markdown memory inside `.opencontext/.md` with built-in write guards and symlink protections. |
| `delete_context` | `topic` *(string)* | Removes an obsolete topic file and automatically rebuilds the topic index. |
---
### ADR Lifecycle & Frontmatter
Topics support optional YAML frontmatter to track lifecycle status — useful when architectural decisions evolve and old context should be visible but clearly flagged as outdated.````markdown
---
description: OAuth2 + PKCE authentication flow
status: active
supersedes: auth_v1
---
# Authentication v2
Migrated from JWT to OAuth2 with PKCE.
````
**Supported frontmatter keys:**
Key · Values · Description
`description` · string · Short summary used in the auto-generated index.
`status` · `active` \ · `deprecated` \ · `superseded` · Lifecycle status. Defaults to `active` when omitted.
`supersedes` · string · Topic name this topic replaces *(set on the newer topic)*.
`superseded_by` · string · Topic name that replaced this one *(set on the older topic)*.
Non-active topics automatically receive `[DEPRECATED]` or `[SUPERSEDED]` badges in the auto-generated `index.md`, along with cross-references showing which topic replaced or was replaced.
---
### Agent Workflows
Instruct your agents to automatically leverage project context. Add this snippet to your `.cursorrules`, `CLAUDE.md`, or system prompt:```markdown
Before making structural code changes, run `read_context` to inspect existing project topics and architectural decisions.
Whenever a new architectural convention, database schema, or API rule is established or refactored, call `save_context` with a concise, topic-scoped markdown summary. Use YAML frontmatter (status, supersedes) when updating conventions to track lifecycle changes.
When a topic becomes obsolete, call `delete_context` to remove it. For deprecated topics that should remain visible, set status: deprecated or status: superseded in the frontmatter instead of deleting.
Configuration
Customize storage paths and security boundaries with an optional .opencontext.json file in your repository root (plain JSON — comments are not supported):```json
{
"path": ".opencontext",
"readOnly": false,
"autoIndex": true,
"guard": {
"enabled": true,
"maxFileSizeKb": 50,
"strictPatternCheck": true
}
}
---
### Local Development```bash
# Clone and install dependencies
git clone [https://github.com/slxca/opencontext.git](https://github.com/slxca/opencontext.git)
cd opencontext
pnpm install
# Build & run tests
pnpm build
pnpm test
Documentation
For advanced setup guides, guard parameters, and agent prompt templates, visit opencntx.dev/docs.
Contributing
Contributions are welcome. Please ensure all unit tests and typechecks pass before submitting a pull request:```bash
pnpm typecheck && pnpm test
```
