OpenContext

Memória persistente e local ao projeto para agentes de IA de codificação.

---

A maioria dos agentes de codificação perde decisões críticas entre sessões: invariantes de arquitetura, contratos de API, padrões rejeitados e peculiaridades de configuração. O OpenContext resolve a perda de contexto por meio de um servidor leve do Model Context Protocol (MCP) que permite que agentes leiam e alterem arquivos markdown duráveis dentro de .opencontext/.

Sem bancos de dados vetoriais, sem assinaturas em nuvem e sem estado oculto. A memória é markdown simples rastreado diretamente no Git.

---

Início Rápido

Execute o servidor MCP diretamente, sem instalação, via npx:

npx -y opencontext-mcp

Configuração em Um Comando

Crie o OpenContext no projeto atual de forma interativa:

npx -y opencontext-mcp init

O init guia você pela configuração (habilitando a integração com OpenCode e Claude Code) e gera tudo o que você precisa:

• .opencontext/ — diretório que contém seus arquivos de tópicos de contexto
• .opencontext.json — modelo de configuração
• opencode.json — entrada do servidor MCP para OpenCode
• .mcp.json — entrada do servidor MCP para Claude Code
• AGENTS.md / CLAUDE.md — lembretes de fluxo de trabalho para seus agentes

O comando init não aceita argumentos: ele sempre é executado no diretório atual, solicita entradas interativamente e nunca sobrescreve uma configuração existente.

Configuração do Cliente

OpenCode

Adicione o OpenContext à configuração MCP do seu projeto (opencode.json) — ou deixe o opencontext-mcp init fazer isso por você:

{
  "mcp": {
    "opencontext": {
      "type": "local",
      "command": ["npx", "-y", "opencontext-mcp"],
      "enabled": true
    }
  }
}

Cursor / Claude Desktop / Windsurf

Adicione o OpenContext ao seu arquivo de configurações MCP (claude_desktop_config.json ou configurações MCP do Cursor):

{
  "mcpServers": {
    "opencontext": {
      "command": "npx",
      "args": ["-y", "opencontext-mcp"]
    }
  }
}

---

Acesso Remoto (HTTP)

Exponha o servidor MCP pela rede com o transporte Streamable HTTP. A URL do endpoint é exibida no stderr na inicialização.

# 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

O servidor escuta em http://<host>:<port>/mcp (Streamable HTTP sem estado — uma solicitação por vez, sem sessões). GET / retorna informações básicas do servidor, útil para uma verificação de saúde no navegador.

---

Ferramentas Principais

Ferramenta	Parâmetros	Descrição
read_context	topic? (string opcional)	Lê um tópico de contexto específico ou retorna o índice leve de tópicos (~100 tokens) se omitido.
save_context	topic (string), content (string)	Escreve ou altera memória markdown dentro de .opencontext/<topic>.md com proteções de escrita e proteções de symlink integradas.
delete_context	topic (string)	Remove um arquivo de tópico obsoleto e reconstrói automaticamente o índice de tópicos.

---

Ciclo de Vida de ADR e Frontmatter

Os tópicos suportam frontmatter YAML opcional para rastrear o status do ciclo de vida — útil quando decisões de arquitetura evoluem e o contexto antigo deve ser visível, mas claramente marcado como desatualizado.

---
description: OAuth2 + PKCE authentication flow
status: active
supersedes: auth_v1
---

# Authentication v2

Migrated from JWT to OAuth2 with PKCE.

Chaves de frontmatter suportadas:

Chave	Valores	Descrição
description	string	Resumo curto usado no índice gerado automaticamente.
status	active | deprecated | superseded	Status do ciclo de vida. O padrão é active quando omitido.
supersedes	string	Nome do tópico que este tópico substitui (definido no tópico mais novo).
superseded_by	string	Nome do tópico que substituiu este (definido no tópico mais antigo).

Tópicos não ativos recebem automaticamente os selos [DEPRECATED] ou [SUPERSEDED] no index.md gerado automaticamente, junto com referências cruzadas mostrando qual tópico substituiu ou foi substituído.

---

Fluxos de Trabalho do Agente

Instrua seus agentes a aproveitar automaticamente o contexto do projeto. Adicione este trecho ao seu .cursorrules, CLAUDE.md ou prompt de sistema:

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.

---

Configuração

Personalize caminhos de armazenamento e limites de segurança com um arquivo .opencontext.json opcional na raiz do seu repositório (JSON simples — comentários não são suportados):

{
  "path": ".opencontext",
  "readOnly": false,
  "autoIndex": true,
  "guard": {
    "enabled": true,
    "maxFileSizeKb": 50,
    "strictPatternCheck": true
  }
}

---

Desenvolvimento Local

# 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

---

Documentação

Para guias de configuração avançados, parâmetros de proteção e modelos de prompt para agentes, visite opencntx.dev/docs.

Contribuição

Contribuições são bem-vindas. Certifique-se de que todos os testes de unidade e verificações de tipo passem antes de enviar um pull request:

pnpm typecheck && pnpm test