kb-graphCAUTION
One coding agent learns; every agent and future session can start knowing it. Inspectable Markdown + SQLite memory over MCP.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
One coding agent learns. Every agent and future session can start knowing it.
[](https://github.com/uttambharadwaj/kb-graph/actions/workflows/test.yml) [](https://github.com/uttambharadwaj/kb-graph/releases/latest) [](package.json) [](LICENSE)
kb-graph gives Claude Code, Codex, Cursor, Gemini, and other MCP clients one shared, searchable knowledge base. Notes remain files you own. The hard problem is not storing them; it is keeping shared truth current as decisions change.
[](docs/assets/terminal-demo.svg) Real-process proof generated by [`scripts/generate-terminal-demo.mjs`](https://github.com/uttambharadwaj/kb-graph/blob/main/scripts/generate-terminal-demo.mjs): three actual kb-graph commands, three fresh Node processes, one isolated temporary `KB_DIR` and vault. Temporary paths, the note date, and expected fresh-store health warnings are normalized. This proves process-to-process persistence, not a cross-agent UI recording.
Storage and retrieval are local. AI curation is not: harvesting, classification, extraction, reconciliation, safety review, and synthesis invoke your authenticated Claude CLI and may send selected transcript or note content to its configured provider. The embedding model is downloaded on first use, then runs locally.
Install from source
Requirements:
- macOS or Linux
- Node.js 22, 24, or 26
- an installed, authenticated
claudeCLI for AI curation - network access on first embedding use to download the model
Registry publication is deferred. Do not u
fe4aa99db5f7OBSERVED · 2026-10-11Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add kb-graph --env BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET} --env KB_API_KEY_CLAUDE=${KB_API_KEY_CLAUDE} --env KB_API_KEY_GEMINI=${KB_API_KEY_GEMINI} --env KB_API_KEY_OPENAI=${KB_API_KEY_OPENAI} -- npx -y [email protected]{
"mcpServers": {
"kb-graph": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"BETTER_AUTH_SECRET": "${BETTER_AUTH_SECRET}",
"KB_API_KEY_CLAUDE": "${KB_API_KEY_CLAUDE}",
"KB_API_KEY_GEMINI": "${KB_API_KEY_GEMINI}",
"KB_API_KEY_OPENAI": "${KB_API_KEY_OPENAI}"
}
}
}
}Exposed tools (15)
14 read · 1 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
firehose | read | |
kb_fact_add | write | Add a temporal fact to the knowledge graph. Facts are subject-predicate-object triples with optional time validity. Use for decisions, relationships, and states that change over time. E.g. ( |
kb_fact_invalidate | read | End an erroneous fact assertion while preserving its raw row, provenance, and validity interval. This is not a current-state selection tool: do not use it merely because evidence is older, duplicated, synonymous, contested, or superseded in meaning; use kb_fact_query and a complete append-only |
kb_fact_query | read | Query the knowledge graph for an entity\ |
kb_fact_timeline | read | Get chronological timeline of facts, optionally for one entity. Shows the story of an entity or the full knowledge graph in order. |
kb_list | read | List documents in the knowledge base, optionally filtered by type or tag. Superseded (retired) notes are excluded unless include_superseded is set. |
kb_read | read | Read a document in full, by ID — after kb_context or kb_search has told you which ID is worth the tokens. The response carries a |
kb_safety_check | read | Review a potentially destructive action before executing it. Searches KB for past incidents, evaluates risk, and returns a safety verdict. Use this before ANY destroy, delete, drop, or force-push operation. |
kb_search | read | Search the knowledge base using full-text search. Returns ranked results with highlighted snippets. Superseded (retired) notes are excluded unless include_superseded is set. |
kb_search_smart | read | Smart search combining keyword matching and semantic similarity. Better than kb_search for conceptual queries like |
kb_tunnels | read | Explore cross-domain connections in the knowledge graph. With one tag: ranked neighboring domains by co-occurrence strength (lift-scored, so big generic tags do not dominate). With two tags: the bridge between them — notes tagged with both, plus entities mentioned in both domains\ |
kb_wakeup | read | Get a token-efficient briefing on what the knowledge base contains. Returns entry counts by type and domain, plus the most recent entries. Use this at the start of a session instead of reading the full index. |
noop | read | |
slow | read | |
whoami | read |
Trust audit
CAUTIONgrade C · trust 73/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (5 observation(s))
- Network
- declared (8 observation(s))
- Shell
- declared (3 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- found
Findings (22)
const response = await fetch(`http://127.0.0.1:${process.env.KB_SMOKE_PORT}/openapi.json`);const secret = 'SECRET_COMMAND_OR_OUTPUT';
const secret = 'sk-123456789012345678901234567890';
token: 'previous-process-at-this-pid',
assert.equal(redactSecrets('before\n-----BEGIN PRIVATE KEY-----\nc2VjcmV0\nbW9yZQ=='),.node-version
return createHash('sha1').update(String(s)).digest('hex').slice(0, 8);new URL('../../eval/checkpoint-replay-v1.json', import.meta.url),export const KB_ENTRYPOINT_PATH = fileURLToPath(new URL('../../bin/kb.js', import.meta.url));const spec = JSON.parse(readFileSync(join(__dirname, '../../openapi.json'), 'utf-8'));
const { buildExtractPrompt, chunkForExtract } = await import('../../src/extract.js');const { runClaude } = await import('../../src/claude-cli.js');insert.run('Beacon vocabulary one', 'beacon vocabulary', 'note', 'misc', null);insert.run('Beacon vocabulary two', 'beacon vocabulary', 'note', 'misc', null);'lantern beacon',
!relevantNotes('propose lantern beacon', { limit: 50 })'beacon',
createOAuthAuth({ baseURL: 'http://127.0.0.1:3838' });const baseURL = 'http://127.0.0.1:3838';
'http://127.0.0.1:3838',
'http://127.0.0.1:4848',
@huggingface/transformers, @modelcontextprotocol/client, @modelcontextprotocol/node, @modelcontextprotocol/server, bcryptjs, better-sqlite3, cors, dotenv
Gates applied: no_behavioural_pass.
fe4aa99db5f7full audit observations/trust-audit/mcp-server/uttambharadwaj__kb-graph.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-11 | fe4aa99db5f7 | CAUTION | C | 73 | first audit |
Questions
What is the kb-graph MCP server?
One coding agent learns; every agent and future session can start knowing it. Inspectable Markdown + SQLite memory over MCP.
What tools does kb-graph expose?
15 in total: 14 read-only, 1 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is kb-graph safe to connect to an agent?
With care. The audit graded it C (73/100) and found 22 things worth knowing before you trust this server, listed below with the exact line each was found on.
What credentials does kb-graph need?
It reads BETTER_AUTH_SECRET, KB_API_KEY_CLAUDE, KB_API_KEY_GEMINI, KB_API_KEY_OPENAI, KB_PASSWORD and MAX_THINKING_TOKENS from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does kb-graph run?
It speaks stdio and streamable-http, so it runs as a local process your client starts. It is published on npm as kb-graph at 2.1.0.
How current is this page?
The grade is for one exact copy of the source (fe4aa99db5f7), read on 2026-10-11. The repository is watched and re-audited when it changes.