@jpereraaracil/mcp-knowledge

MCP Knowledge Base server for OpenCode. Store and retrieve Markdown notes with metadata, search, and relationships — persisted between sessions.

Features

• Markdown notes with YAML frontmatter (tags, relations, metadata)
• Full CRUD operations
• Regex search with tag/folder filtering
• Bidirectional relationships between notes (wiki-style graph)
• Session persistence: save context between OpenCode sessions
• Auto-organizes into subfolders
• Works with Bun and Node.js

Installation

npm install @jpereraaracil/mcp-knowledge

Configuration

Add to your OpenCode config (opencode.json or .opencode/config.json):

With npx (no install needed)

{
  "mcpServers": {
    "knowledge": {
      "command": "npx",
      "args": ["-y", "@jpereraaracil/mcp-knowledge"]
    }
  }
}

With bun (if installed globally)

{
  "mcpServers": {
    "knowledge": {
      "command": "bun",
      "args": ["run", "mcp-knowledge"]
    }
  }
}

Storage

Notes are stored in your project at .knowledge/notes/:

your-project/
  .knowledge/
    notes/
      arquitectura/
        auth-flow.md
      sesiones/
        2026-05-23-session-001.md
      some-note.md

Each note has YAML frontmatter:

---
id: auth-flow
title: Auth Flow
tags: [auth, arquitectura]
created: 2026-05-23T10:00:00Z
updated: 2026-05-23T10:00:00Z
related: [session-mgmt]
folder: arquitectura
---

Note content in Markdown...

Tools

| Tool | Description | |---|---| | kb_create | Create a note (title, content, tags, folder, related) | | kb_read | Read a note by ID | | kb_update | Update note fields (title, content, tags, related) | | kb_delete | Delete a note and clean up all references | | kb_search | Search by text (regex), tags, and/or folder | | kb_list | List notes filtered by tags/folder, sorted by recent | | kb_link | Create bidirectional link between two notes | | kb_unlink | Remove bidirectional link | | kb_graph | Get relationship graph up to 3 levels deep | | kb_session_save | Save session context (summary, decisions, pending, files) | | kb_session_load | Load recent session contexts |

Resources

| Resource URI | Description | |---|---| | knowledge://index | Index of all notes | | knowledge://note/{id} | Single note content | | knowledge://graph/{id} | Relationship graph for a note | | knowledge://sessions/latest | Latest session contexts |

Session Persistence

Save context at the end of a session so the next session can pick up where you left off:

kb_session_save({
  summary: "Implemented JWT auth with refresh tokens",
  decisions: ["Use httpOnly cookies for refresh tokens"],
  pending: ["Write tests for auth middleware", "Add rate limiting"],
  files_modified: ["src/auth.ts", "src/middleware.ts"]
})

Load it back in the next session:

kb_session_load({ limit: 3 })

Add to your AGENTS.md to auto-save context:

At the end of every session, use kb_session_save to persist the session context.

Environment Variables

| Variable | Default | Description | |---|---|---| | KNOWLEDGE_DIR | .knowledge (in project root) | Override knowledge base directory path |

License

MIT