Skip to main content
Glama

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

item_search, item_get, item_save, item_delete, item_graph

Buscar, ler, gravar (idempotente por key), remover e navegar links entre itens.

Hierarquia

workspace_*, project_*, subject_* (list/create/update/merge/delete)

Organizar onde cada item vale (empresa/cliente → repositório → conceito).

Relações & tags

relation_create/delete, tag_list/create/update/delete

Ligar itens (depends_on/relates_to) e dar nuance por tags.

Repositório

repo (link/list/unlink/sync)

Ligar o repo em que você trabalha a um workspace/project.

Conexão & saúde

connection_create/list/delete, health_check

Criar/listar a pasta git de dados e checar o estado do servidor.

Related MCP server: arcane

Taxonomia dos itens

Tipo

Guarda

rule

o que deve ser seguido + o porquê (convenção, decisão, regra de negócio)

howto

passos repetíveis ou diagnóstico (sintoma/causa/solução)

context

pano de fundo: produto, mapa, stack, glossário, ambiente

work

o trabalho: plano/spec + decisões (o porquê durável); ciclo por tag

secret

referência a um segredo (sem o valor)

Campo

Valores

tags de ciclo

draft, active, done, archived

tags de nuance (base, extensível)

decision, troubleshoot, security, pattern, map, glossary, product, environment, business, process

link item→item (rel)

depends_on, relates_to

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: gh autenticado (só para conexões com remote_url e revisão por PR); keyring do SO (só se usar itens secret).

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-mcp

Cursor (~/.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

LOG_LEVEL

Nível de log (recomende WARNING nos clientes MCP).

INFO

KNOWLEDGE_OS_HOME

Estado local da máquina (conexões, cache) — não guarda itens.

~/.knowledge-os

KNOWLEDGE_OS_UI

1 sobe a UI local em 127.0.0.1:8765 junto com o servidor; 0 desliga.

1

Não coloque KNOWLEDGE_OS_VAULT_KEY na 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_search devolve resumos, nunca o content completo por acidente.

  • Itens secret ficam 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 com confirm=True.

Available Tools

15 tools
artifact_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

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

    A4/5.0

    Scored across 15 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Gives AI coding agents persistent, evolving knowledge about a codebase, enabling them to store and retrieve observations about architecture, conventions, gotchas, and recent work context.
      10
      57 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides persistent, searchable memory and knowledge capture for AI-assisted development, enabling agents to retain decisions, bugs, and patterns across sessions and projects.
      265 PyPI
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      3
      MIT