# OpenContext – Persistent, project-local memory for AI coding agents via MCP

> Source: <https://www.opencntx.dev/>
> Published: 2026-08-29 23:24:44+00:00

# Persistent, Project-Local Memory for AI Coding Agents

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.