TypeScript · Knowledge graph RAG · MCP
kontext-brain-ts
An open-source knowledge layer for AI agents, with retrieval you can trace back to source evidence.
Kontext Brain (repository: kontext-brain-ts; packages: @kontext-brain/*) is a TypeScript / Node.js framework for retrieval-augmented generation. It connects documents to Resources, Chunks, Entities, Facts, and Evidence, and supports hybrid retrieval and MCP integration.
When to use Kontext Brain
| Your requirement | Relevant part of the project |
|---|---|
| RAG in a TypeScript app | Use the loader and agent APIs to retrieve context or produce an evidence-backed answer. |
| Knowledge for an MCP client | Run the tool server so a compatible AI client can query the knowledge base without embedding the library. |
| Permission-aware team knowledge | The PostgreSQL runtime supports organization RLS and ACL-aware retrieval. Configure the principal and source permissions for your deployment. |
| Local experimentation | Use the lightweight file store and Ollama adapters. The file store does not provide the production PostgreSQL permission model. |
Implementation: agent APIs · MCP tools · PostgreSQL runtime.
How retrieval works
Source documents → Resources and Chunks
→ Entities, Facts and Evidence
Question + user permissions → candidate retrieval
→ bounded graph traversal
→ source evidence → answer
External systems remain the source of truth. Kontext maintains a derived knowledge index. Its production retrieval path starts from accessible resources, chunks, entities, facts, or optional ontology anchors, then follows a bounded Lift → Expand → Ground traversal. Source text is loaded for the evidence selected for answering.
Vector and keyword retrieval can be combined with graph context. The runtime exposes separate retrieval and answer paths, allowing an agent to use the context in its own reasoning flow. Evidence identity and source links help developers inspect where an answer came from.
See the design decisions for the derived evidence index, storage and permissions, and N-layer retrieval.
Start from the repository
You need Node.js 20 or later, pnpm 9, and an LLM/embedding provider configured for the example you run. Ollama is supported for local models; hosted providers require their own credentials and may incur costs.
git clone https://github.com/hj1105/kontext-brain-ts.git
cd kontext-brain-ts
corepack enable
pnpm install
pnpm -r build
# After configuring a provider as described in the README:
pnpm --filter @kontext-brain/example-basic startFollow the complete quick start for provider setup and the auto-setup example for mock MCP sources. For an MCP host, build the repository and configure the host to run packages/tool-server/dist/cli.js with your kontext.yaml. The MCP setup instructions show the command and configuration.
Evaluate it with its limits in view
- Self-hosted software: the repository is Apache-2.0 licensed. A managed cloud service is a product direction, not a hosted signup offered by this page.
- Connector validation: MCP connector synchronization has mock-based coverage. The published project status still calls out real Notion, GitHub, and Slack server end-to-end smoke tests as pending.
- Permissions depend on configuration: the production PostgreSQL path and local file-store path have different security and storage capabilities.
- Benchmarks are development evidence: the evaluation profiles were tuned iteratively and some comparisons reuse precomputed graphs. Evaluate on your own corpus and access rules before adopting the framework.
Review the current project status and evaluation protocol. This overview does not claim a universal accuracy score or a ranking over other frameworks.
Questions developers ask
- Is kontext-brain-ts an LLM?
- It is a retrieval and knowledge framework. It uses configured language and embedding models; it does not supply a newly trained foundation model.
- How is it different from a vector-only RAG pipeline?
- It models resources, source chunks, entities, facts, and evidence explicitly. Its production path adds permission-aware graph retrieval and source grounding alongside vector and keyword search. Whether this helps depends on your corpus and workload.
- Does it support MCP?
- Yes. The MCP package consumes compatible source servers, while the tool-server package exposes retrieval and knowledge operations to compatible clients. See the implementation links above for the current tools.
- Can I run it locally?
- Yes. The repository includes a lightweight local path and Ollama provider support. Production storage and permission enforcement require the corresponding infrastructure and configuration.
- Is the software free to use?
- The code is available under Apache-2.0. Hosting, storage, model APIs, and operations can have separate costs.
Inspect before you integrate
The repository contains the APIs, examples, architecture decisions, and evaluation protocol. Start with the small example, then test retrieval and permissions against your own data.