# ContextLib

> ContextLib is an open-source MCP server for files and documents. Project memory kept as plain Markdown files with a tamper-evident append-only log. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, macOS
- **Website:** https://huggingface.co/spaces/willykeenan/contextlib
- **Repository:** https://github.com/willykeenan/agentbrain-contextlib
- **MCP Registry name:** io.github.willykeenan/agentbrain-contextlib
- **Categories:** files and documents, knowledge and memory, developer tools
- **Listing updated:** 2026-11-16

## About

Decisions, requirements, facts, lessons, glossary entries, sources and returned work are saved as Markdown files with a small front-matter block, one folder per project. The folders can live on an external drive, and a person can follow a project from the file browser alone. Any database is only a rebuildable search index, never the source of truth.

Agents use the same files through a stdio server whose tools are prefixed with `context_`, or through the `ctxlib` command line tool. Records an agent proposes wait in an inbox until a person accepts or rejects them, so an owner's decision lands as current while an agent's lesson is held back. Records can carry evidence, review-by dates and approvers, and a newer record can supersede an older one while keeping the earlier body hash. A health check command reports problems in plain English, and the README mentions that a secret is refused when written.

It is the open core of the context plugin of AgentBrain, needs only the Python standard library (3.9 or newer), and optionally syncs through git.

## Features

- **Markdown storage:** Keeps knowledge as readable files with front matter, one folder per project.
- **Proposal inbox:** Holds agent-proposed records until a person accepts or rejects them.
- **Supersession chain:** Replaces old records while preserving the body hash and reason.
- **Review dates:** Flags records whose review-by date has passed.
- **Rebuildable index:** Uses SQLite search that can be regenerated from the files.
- **Health check:** Reports library problems in plain English.
- **Export and import:** Zips a project and imports it elsewhere, with private records excluded by default.

## Good for

- Give coding agents durable project memory across sessions
- Record decisions and requirements a team can read without special tools
- Review and approve lessons an agent proposes
- Carry project knowledge to another machine as files
- Find when a recorded fact is due for review

## Install

### Claude Code (Terminal)

```sh
claude mcp add agentbrain-contextlib -- docker run -i --rm ghcr.io/willykeenan/agentbrain-contextlib:0.1.0
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "agentbrain-contextlib": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/willykeenan/agentbrain-contextlib:0.1.0"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "agentbrain-contextlib": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/willykeenan/agentbrain-contextlib:0.1.0"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "agentbrain-contextlib": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/willykeenan/agentbrain-contextlib:0.1.0"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "agentbrain-contextlib": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/willykeenan/agentbrain-contextlib:0.1.0"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "agentbrain-contextlib": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/willykeenan/agentbrain-contextlib:0.1.0"
      ]
    }
  }
}
```

## FAQ

### Where is the data kept?

In plain Markdown files in a folder you choose, such as an external drive.

### What if the search database is lost?

It can be rebuilt from the files, which are the source of truth.

### Can an agent change decisions on its own?

Agent-proposed records go to an inbox and become current only when accepted.

### What does it need to run?

Python 3.9 or newer and no third-party packages; Git is optional.

### Is ContextLib free?

Yes. ContextLib is open source, so you can use and self-host it for free.

### How do I add ContextLib to Claude Code?

Run this command in your terminal: claude mcp add agentbrain-contextlib -- docker run -i --rm ghcr.io/willykeenan/agentbrain-contextlib:0.1.0

### What are the best alternatives to ContextLib?

The closest alternatives to ContextLib are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/contextlib
