Knowledge OS
Knowledge OS is a local MCP "second brain" that stores durable project knowledge as Markdown in a git folder and provides tools to retrieve, save, organize, back up, and attach artifacts to that memory.
Search and read memory:
item_searchreturns summaries;item_getfetches full items, tags, relations, and attachments.Save/update/delete knowledge:
item_savecreates, upserts by key/id, updates, deprecates/supersedes, adds relations/scope paths/tags, stores secret references (no values), and creates ephemeral notes;item_deleteremoves items.Get project context:
context_getassembles a token-budgeted context package focused by project/paths/query and flags sensitive areas.Link and organize projects:
project_linkconnects a repo to a workspace/domain;structure_listshows the workspace/domain tree;structure_deleteremoves a domain/workspace after preview/confirm.Manage relations and vocabulary:
relation_deleteremoves item relations;vocabularylists/creates/deletes tags and controlled labels.Back up and restore:
backup_exportexports a workspace/domain to ZIP;backup_importrestores from a backup ZIP.Attach files:
artifact_attachcopies a local file to an item;artifact_getreturns an attachment as base64.Check health:
health_checkreports server, database, schema, and toolset status.Safety features: data stays in local git/loopback, search avoids full content, secrets are encrypted outside git via OS keyring, and destructive operations require preview/
confirm=True.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Knowledge OS quais regras e decisões valem para este repositório?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
knowledge-os-mcp-server
Servidor MCP de memória durável (um "segundo cérebro") para agentes: guarda regras, decisões e o porquê, how-tos, contexto e specs como arquivos Markdown numa pasta git sua, e os devolve ao agente com baixo custo de contexto.
O que faz
A memória vive como arquivos .md (com frontmatter) numa pasta git que você escolhe — é sua, versionada, inspecionável. O agente consulta antes de agir e grava o que dura. Cinco tipos de item: rule, howto, context, work, secret. O alcance vem da hierarquia workspace → project → subject.
As 31 tools se agrupam em:
Área | Tools | Para quê |
Itens |
| Buscar, ler, gravar (idempotente por |
Hierarquia |
| Organizar onde cada item vale (empresa/cliente → repositório → conceito). |
Relações & tags |
| Ligar itens ( |
Repositório |
| Ligar o repo em que você trabalha a um workspace/project. |
Conexão & saúde |
| Criar/listar a pasta git de dados e checar o estado do servidor. |
Related MCP server: arcane
Taxonomia dos itens
Tipo | Guarda |
| o que deve ser seguido + o porquê (convenção, decisão, regra de negócio) |
| passos repetíveis ou diagnóstico (sintoma/causa/solução) |
| pano de fundo: produto, mapa, stack, glossário, ambiente |
| o trabalho: plano/spec + decisões (o porquê durável); ciclo por tag |
| referência a um segredo (sem o valor) |
Campo | Valores |
tags de ciclo |
|
tags de nuance (base, extensível) |
|
link item→item ( |
|
Key: <tipo>/<nome> (nome em minúsculas com -); fora do padrão grava com aviso, e a key de um item existente nunca muda.
Alcance: o item vale onde mora na hierarquia (workspace → project → subject) e abaixo. Não há scope, status, subtype, origin nem expiração — a nuance e o ciclo vão em tags.
links (unificado): {item, rel} liga a outro item; {url[, title]} a uma URL; {path} a um arquivo/glob do repositório.
Requisitos
Python 3.12+.
git (CLI) — obrigatório: cada "conexão" é um repositório git e cada escrita é um commit.
Opcionais:
ghautenticado (só para conexões comremote_urle revisão por PR); keyring do SO (só se usar itenssecret).
Instalação
uv tool install knowledge-os-mcp-server # disponibiliza o comando `knowledge-mcp`
# (alternativa: pip install knowledge-os-mcp-server)Configuração
1. Registre no cliente MCP
Claude Code:
claude mcp add --scope user knowledge-os -e LOG_LEVEL=WARNING -- knowledge-mcpCursor (~/.cursor/mcp.json) e similares:
{
"mcpServers": {
"knowledge-os": {
"command": "knowledge-mcp",
"env": { "LOG_LEVEL": "WARNING" }
}
}
}O servidor fala por stdio; não precisa de args. (Se preferir não instalar, use "command": "uvx", "args": ["--from", "knowledge-os-mcp-server", "knowledge-mcp"].)
2. Crie a primeira pasta de dados e ligue seu repo
Nada funciona sem ao menos uma conexão (a pasta git dos dados). Pelo agente, uma vez:
connection_create(name, path)— cria/usa a pasta git onde a memória será guardada.Dentro do repositório em que você trabalha:
repo(action="link", repo=".")— o project passa a ser esse repo; o workspace, o dono do remote.
Variáveis de ambiente (todas opcionais)
Variável | Efeito | Default |
| Nível de log (recomende |
|
| Estado local da máquina (conexões, cache) — não guarda itens. |
|
|
|
|
Não coloque
KNOWLEDGE_OS_VAULT_KEYna config do MCP nem no ambiente do agente — ela é a chave mestra do cofre de segredos e só serve para CI/máquinas sem keyring.
Segurança
Os dados são seus arquivos git — nada sai da sua máquina; a UI local escuta só em loopback.
item_searchdevolve resumos, nunca ocontentcompleto por acidente.Itens
secretficam cifrados fora do git, na pasta.secrets/da conexão; a chave vive no keyring do SO.Operações destrutivas (
*_delete) devolvem prévia e só executam comconfirm=True.
Available Tools
15 toolsartifact_attachArtifact AttachA
Anexa um arquivo local a um item (copiado para /artifacts, até 100 MB).
Use quando: O valor do item é um arquivo (diagrama, template, script). Retorna: Metadados do anexo (id, filename, file_size, mime_type). Exemplo: artifact_attach(item_id="...", file_path="C:/docs/arquitetura.png") Notas: Use só caminhos que o usuário indicou. A lista vem em item_get → artifacts.
Inputs: item_id (required), file_path (required), connection_id. Returns: object
artifact_getArtifact GetB
Conteúdo de um anexo em base64.
Use quando: Precisar do arquivo em si (confira file_size em item_get antes). Retorna: {artifact, content_base64}. Exemplo: artifact_get(artifact_id="...")
Inputs: artifact_id (required), connection_id. Returns: object
backup_exportBackup ExportA
Exporta um workspace (ou só um domain) para um ZIP em /exports.
Use quando: Antes de mudanças grandes ou para levar conhecimento a outra máquina. Retorna: {status: ok, file_path, size_mb}. Exemplo: backup_export(workspace="agenda-api") · backup_export(workspace="agenda-api", domain="projpro") Notas: backup_import restaura (o workspace importado ganha ids novos).
Inputs: workspace (required), domain, connection_id. Returns: object
backup_importBackup ImportA
Importa um ZIP de backup_export: workspace inteiro, ou um domain dentro de workspace.
Use quando: Restaurar um backup ou trazer conhecimento de outra máquina. Retorna: {status: ok, ...workspace ou domain criado}. Exemplo: backup_import(file_path="C:/x/workspace_....zip") Notas: Use só caminhos que o usuário indicou. Nome de workspace já existente é recusado.
Inputs: file_path (required), workspace, connection_id. Returns: object
context_getContext GetA
Pacote de contexto do projeto: regras, contexto, decisões, padrões, procedimentos.
Use quando: Começar num projeto (se o hook não injetou) ou ao passar a mexer em outra
área: paths traz as regras com escopo daqueles arquivos; query, itens relacionados.
Retorna: {linked, project_key, workspace, domain, markdown, included, omitted, sensitive}.
Exemplo: context_get(project=".", paths=["src/payments/Charge.java"], query="estorno")
Notas: Dentro de budget_tokens. Itens que casam com paths ou query vêm em foco, com o
começo do content (dispensa item_get); o resto, só título, resumo e key. sensitive é true
se paths toca uma área marcada com a keyword "sensivel". Inclui o domain do projeto,
Geral do workspace e Global/Geral. Sem substituídos, obsoletos nem ephemeral.
Inputs: project (required), paths, query, budget_tokens, +1 more. Returns: object
health_checkHealth CheckA
Verifica a saúde do servidor MCP e do banco default.
Use quando: Diagnosticar falhas ou confirmar que o servidor está operacional. Retorna: {status: ok|error, database: connected | motivo, version, schema_version, toolset}. Exemplo: health_check() Notas: Valida a conexão e a presença de todas as tabelas (inclusive a de busca textual).
Inputs: no named parameters. Returns: object
item_deleteItem DeleteA
Remove um item de vez (com tags, relações e anexos). Destrutivo.
Use quando: O item está errado e não há histórico a preservar. Retorna: {status: deleted, id}. Exemplo: item_delete(item_id="...") Notas: Para aposentar mantendo o histórico, prefira item_save com status=deprecated ou uma relação supersedes.
Inputs: item_id (required), connection_id. Returns: object
item_getItem GetA
Lê itens completos (content, tags, relações, anexos) por id e/ou key, vários de uma vez.
Use quando: O resumo da busca ou do contexto não bastou. Retorna: Lista de itens completos, na ordem pedida; o que não existe vem como {key|id, missing: true}, sem derrubar os outros. Exemplo: item_get(keys=["regra/money", "proc/deploy"], project=".") Notas: keys exigem project (o domain ligado) ou workspace e domain. Até 20 por chamada.
Inputs: ids, keys, domain, project, +2 more. Returns: result
item_saveItem SaveA
Grava itens (criar, atualizar, upsert, renovar, relacionar) numa transação.
Use quando: Guardar o que vale para depois — uma regra que o usuário enunciou, as
decisões e aprendizados ao fechar uma mudança, uma correção de um item.
Retorna: [{index, id, key, action: created|updated|unchanged, similar?, relations?}].
Modo, por entrada: com key → upsert no domain (não duplica; o preferido); com id →
atualiza o item; sem os dois → cria e devolve similar (títulos parecidos já guardados).
Exemplo (upsert): item_save(project=".", items=[{"key": "regra/money", "type": "rule",
"title": "Money em pagamentos", "summary": "Valores em Money, nunca double",
"content": "...", "scope_paths": ["src/payments/**"], "source": "PAY-142"}])
Exemplo (aposentar): item_save(project=".", items=[{"key": "regra/x",
"status": "deprecated"}])
Exemplo (substituir): item_save(project=".", items=[{"key": "proc/deploy-v2", ...,
"relations": [{"type": "supersedes", "target": "proc/deploy"}]}])
Campos: type (rule, insight, procedure, pattern, knowledge, context, artifact, task),
title, summary, content, keywords, source, scope_paths, status (active, done,
superseded, deprecated), memory_class "ephemeral" + ttl_days só para nota temporária
(sem aprovação: o resto já vale), tags, labels, relations
[{type: related_to|depends_on|implements|references|supersedes|derived_from, target: id
ou key}], workspace/domain (sem eles vale o domain ligado a project).
Segredo: {"key": "segredo/npm-token", "type": "secret", "title": "Token do npm",
"summary": "publicar no npm"} — sem valor (é recusado); a resposta traz fill_url:
passe ao usuário para ele preencher na UI local. Usar: knowledge-mcp run --env NPM_TOKEN=segredo/npm-token -- <comando>.
Notas: Um erro desfaz o lote e aponta a entrada. Conteúdo com cara de segredo é recusado.
Inputs: items (required), project, connection_id. Returns: result
item_searchItem SearchA
Busca por texto. Devolve resumos, nunca o conteúdo completo.
Use quando: Procurar algo que pode já estar guardado (decisão, gotcha, procedimento).
Retorna: [{id, key, type, memory_class, domain, title, summary, score, uses}].
Exemplo: item_search(query="migração flyway", limit=5)
Notas: Sem project/workspace, busca no projeto da pasta atual (se ligado) — não vaza para
outros projetos; everywhere=True busca em todos. Relevância primeiro; acentos e plurais
não atrapalham. include_inactive traz substituídos, obsoletos e ephemeral vencidos.
Inputs: limit, query, types, domain, +6 more. Returns: result
project_linkProject LinkA
Liga um repositório a um workspace/domain do segundo cérebro.
Use quando: Configurar um projeto pela primeira vez (o /plumb-setup faz isso).
Retorna: {project_key, workspace, domain}.
Exemplo: project_link(project=".") → domain = repo; workspace = o de outro repo do
mesmo dono já ligado (no primeiro, o nome do dono; sem remote, Pessoal).
Organização: workspace = contexto (empresa, cliente, Pessoal); Geral do workspace = o
que vale para os repos dele; Global = o que vale em qualquer lugar.
Notas: project aceita caminho (qualquer pasta do repo), URL do remote ou chave; a chave é
o remote do git normalizado (ou o caminho, sem remote). Workspace e domain são criados se
não existirem. Religar move o projeto.
Inputs: project (required), domain, workspace, connection_id. Returns: object
relation_deleteRelation DeleteA
Remove uma relação entre itens (o id vem em item_get → relations).
Use quando: Uma relação foi criada por engano. Retorna: {status: deleted, id}. Exemplo: relation_delete(relation_id="...") Notas: Remover um supersedes não reativa o alvo: ajuste o status com item_save.
Inputs: relation_id (required), connection_id. Returns: object
structure_deleteStructure DeleteA
Remove um domain (ou o workspace inteiro) com todos os itens. Destrutivo.
Use quando: O usuário pediu explicitamente para apagar.
Retorna: Sem confirm: {status: preview, would_delete}. Com confirm: {status: deleted}.
Exemplo: structure_delete(workspace="Teste", confirm=True)
Notas: Chame primeiro sem confirm e mostre o preview ao usuário. Prefira backup_export
antes, e status=deprecated (item_save) quando o histórico importar.
Inputs: workspace (required), domain, confirm, connection_id. Returns: object
structure_listStructure ListA
Árvore workspaces → domains com a contagem de itens.
Use quando: Ver o que existe antes de organizar, ligar um projeto ou fazer backup. Retorna: [{workspace, description, items, domains: [{name, items}]}]. Exemplo: structure_list() · structure_list(workspace="agenda-api") Notas: Criar workspace/domain é implícito em item_save e project_link.
Inputs: workspace, connection_id. Returns: result
vocabularyVocabularyA
Vocabulário da base: tags (livres) e labels (lista controlada).
Use quando: Reaproveitar tags existentes antes de criar variações, ou gerir labels. Retorna: list → [{id, name}]; create → {id, name}; delete → {status: deleted}. Exemplo: vocabulary(kind="tags") · vocabulary(kind="labels", action="create", name="lgpd") Notas: kind: tags | labels. action: list | create (name) | delete (id). Tags também são criadas direto no item_save.
Inputs: id, kind, name, action, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct resource and action: three deletes (item_delete, relation_delete, structure_delete) are explicitly scoped to different objects, and the three retrieval tools are clearly delineated (item_search returns summaries, item_get returns full items, context_get returns a curated project bundle). Descriptions add explicit 'use when' guidance that prevents misselection.
The dominant pattern is consistent snake_case resource_action (item_save, item_get, artifact_attach, structure_delete, backup_export, project_link, relation_delete, context_get). A couple of names deviate from the verb_noun scheme (vocabulary has no verb; health_check is noun_noun), but overall it is predictable and readable.
15 tools is well-scoped for a knowledge-management server spanning items, relations, artifacts, structure, backups, vocabulary, context, and health. Each tool earns its place with no redundant or filler entries.
Coverage is strong: items have save/read/search/delete, relations have create (via item_save) plus delete, artifacts attach/get, structure list/delete, and backup export/import. Minor gaps exist (no explicit artifact detach, workspace/domain rename, or description edit) but core lifecycle workflows are fully covered.
Related MCP Connectors
Project memory, documentation and controlled secret access for AI coding agents.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Private memory for AI agents: save and recall facts across Claude Code, Codex, Cursor and ChatGPT.
Related MCP Servers
- AlicenseAqualityDmaintenanceGives AI coding agents persistent, evolving knowledge about a codebase, enabling them to store and retrieve observations about architecture, conventions, gotchas, and recent work context.1057 npm3MIT
- AlicenseNot gradedqualityBmaintenanceProvides persistent, searchable memory and knowledge capture for AI-assisted development, enabling agents to retain decisions, bugs, and patterns across sessions and projects.265 PyPIMIT
- AlicenseAqualityAmaintenanceProvides long-term memory for AI coding agents, enabling facts like stack, conventions, and decisions to be recorded once and recalled across sessions.8344 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to persist and retrieve durable project knowledge across coding sessions, capturing decisions, conventions, lessons and reusable skills through ordinary chat requests. It supports searching, editing and reviewing saved items, and promoting local notes into Git-shareable versioned knowledge alongside repository changes.234 npm3MIT