Knowledge Forest MCP — Personal Knowledge & Learning Memory

A local-first personal knowledge management (PKM) and learning-memory MCP server for any AI tutor.

Turn goals into prerequisite-aware knowledge trees, preserve learning history, and require real evidence before claiming mastery.

中文 · MCP Registry · Product principles · Architecture · Contributing

Is this the MCP server you are looking for?

Choose Knowledge Forest when you want an AI tutor or learning assistant to remember more than chat history:

Personal knowledge management: keep learner-owned goals, concepts, notes, sources, and evidence in portable local JSON.
Learning memory across chats: let Claude, Codex, or another MCP host resume from the same durable learning state.
A reusable knowledge graph: share one canonical concept and its learning history across multiple goals.
Adaptive learning: expose prerequisites, blocked concepts, desired depth, and the next actionable learning node.
Evidence-based mastery: require novel, unassisted, closed-book performance before a concept becomes verified.

This is not a vector database, document RAG server, or general-purpose transcript memory. It models what a person is trying to learn, how concepts depend on one another, and what evidence actually demonstrates mastery.

Why it exists

AI tutors are excellent at explaining a topic and terrible at owning long-lived learning state. A chat can sound productive while forgetting prerequisites, duplicating concepts across projects, or treating a polished answer as mastery.

Knowledge Forest gives the model a durable learning layer:

Goal trees connect an observable outcome to the minimum knowledge needed to reach it.
Canonical nodes let one concept serve several goals without copying its learning history.
Evidence-gated mastery distinguishes reading and assisted practice from novel, closed-book performance.
Local-first storage keeps the learner's goals, notes, and evidence in a portable JSON file.
Model-neutral MCP works with any compatible host. The host's model does the reasoning and pays its own token cost; this server does not call an LLM.

Quick start

Requirements: Node.js 22 or newer.

Run from GitHub in any stdio MCP host

npx --yes github:znecho9/knowledge-forest-mcp doctor
npx --yes github:znecho9/knowledge-forest-mcp

Install as an MCP Bundle

Clients that support MCPB can install the self-contained bundle from the latest GitHub release. The bundle includes the server and its runtime dependencies; Node.js 22 or newer is still required.

Develop locally

git clone https://github.com/znecho9/knowledge-forest-mcp.git
cd knowledge-forest-mcp
npm ci
npm run check
npm run dev

The default data file is ~/.knowledge-forest/knowledge-forest.json. Override it with KNOWLEDGE_FOREST_FILE or --data-file.

Connect an MCP host

Use the exact data path you want the host to access.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.knowledge-forest]
command = "npx"
args = ["--yes", "github:znecho9/knowledge-forest-mcp"]
env = { KNOWLEDGE_FOREST_FILE = "/absolute/path/to/knowledge-forest.json" }

Claude Desktop and JSON-configured hosts

{
  "mcpServers": {
    "knowledge-forest": {
      "command": "npx",
      "args": ["--yes", "github:znecho9/knowledge-forest-mcp"],
      "env": {
        "KNOWLEDGE_FOREST_FILE": "/absolute/path/to/knowledge-forest.json"
      }
    }
  }
}

Generate both snippets with the resolved path:

npx --yes github:znecho9/knowledge-forest-mcp config --data-file /absolute/path/to/knowledge-forest.json

What the model can do

MCP capability	Purpose	Changes data?
`forest_overview`	See goals, progress, and ready work	No
`search_knowledge`	Find reusable canonical nodes	No
`get_node_context`	Read relationships, notes, and evidence	No
`diagnose_node`	Identify prerequisite, depth, and evidence gaps	No
`get_learning_queue`	Find ready and blocked nodes	No
`create_goal_tree`	Persist a minimal sufficient knowledge tree	Yes
`update_node_learning_state`	Set depth or workflow state	Yes
`append_learning_note`	Append notes, sources, reflections, or exercises	Yes
`record_verification`	Record evidence and enforce the mastery rule	Yes
`export_forest`	Read the complete portable archive	No

The included plan_learning_goal prompt guides a host through search, explicit reuse, and tree creation.

Mastery is deliberately hard to fake

record_verification marks a node verified only when all four conditions are true:

demonstrated
AND closed_book
AND NOT assisted
AND novel_prompt

Source-visible research, explanations, summaries, and hinted answers remain useful learning records, but never become mastery evidence. Other tools cannot set verified directly.

Works with the Knowledge Forest workbench

The storage envelope and core goal/node fields are compatible with the local Knowledge Forest workbench's learning/knowledge-forest.json shape. Point the MCP server at that file to let an AI host and the workbench share one canonical forest:

KNOWLEDGE_FOREST_FILE=/path/to/workbench/learning/knowledge-forest.json \
  node dist/cli.js doctor

Before sharing a live workbench file, commit or back it up. The server performs atomic writes, cross-process locking, validation, and retains the latest 20 MCP snapshots under learning/backups/. MCP-only append records are also mirrored to an adjacent knowledge-forest.mcp-records.json sidecar so a workbench autosave that knows only the core schema cannot erase them; export merges everything into one portable archive.

Local-first guarantees

No model API key is needed.
No network request is made by the server.
No telemetry is collected.
No delete tool is exposed in v1.
Every mutation is schema-validated and written atomically.
Concurrent local writers use a lock to avoid lost updates.
The archive is readable JSON and can be exported with knowledge-forest-mcp export.

Open-core boundary

Everything required for a single learner to build, inspect, verify, back up, and move a forest is Apache-2.0 open source. Possible paid services—none are required by this server—include encrypted multi-device sync, hosted remote MCP, managed backups, organization controls, and premium connectors. See the product brief for the explicit boundary.

Frequently asked questions

Is there an MCP server for personal knowledge management?

Yes. Knowledge Forest is a local-first PKM MCP server focused on learning state rather than document storage. It gives an AI host structured tools for goals, reusable concepts, prerequisites, notes, evidence, and progress.

Can an AI tutor remember my progress across chats?

Yes. Point each compatible host at the same Knowledge Forest JSON file. The MCP server persists the learner model independently of any single chat or model provider.

Is this a knowledge graph MCP server?

Yes, with a deliberately narrow graph: canonical knowledge nodes, prerequisite relationships, goal membership, learning records, and verification evidence. It does not attempt to extract a general entity graph from every document.

How is it different from a general AI memory MCP?

General memory usually optimizes saving and recalling context. Knowledge Forest optimizes learning progression: what the learner wants to achieve, what must be learned first, what can be reused, what is blocked, and whether mastery has been demonstrated.

Status

0.1.1 is a public alpha. The data schema is versioned, but tool contracts may still evolve before 1.0. Back up real learning data and review release notes before upgrading.

Security and contributions

Please report vulnerabilities privately as described in SECURITY.md. Bug reports and focused pull requests are welcome; start with CONTRIBUTING.md.