Bring useful knowledge into an ongoing conversation, even when the user has not asked a question or requested a search.
XKB keeps source-linked Markdown cards, wiki topics and captured conversation traces under your control. MCP, HTTP and the default CLI clients use one recall core, so connected agents can search the same library with the same access rules and relevance checks.
The goal is timely knowledge reuse: notice a plan, obstacle, constraint or decision,
then bring back evidence that helps with that need. Recent dialogue can accompany
the current utterance so follow-ups retain their meaning. The Claude hook does this
on prompt submission; MCP clients must invoke recall proactively as part of their
conversation workflow. Connecting the tool alone does not make an agent use it.
Self-hosted knowledge for AI agents that brings relevant notes, cards and past conversations into an ongoing chat, even when nobody asked. One shared MCP/HTTP recall service; sources stay as linked Markdown you control.
In the bundled synthetic library, asking “Aurora deployment” returns both recorded approaches:
Evidence
What it says
aurora-blue
Use blue-green releases.
aurora-canary
Use canary releases instead of blue-green.
These are fixture records, not a production benchmark. The example shows what recall is for: return the relevant sources, preserve their differences, and let the answering agent reason from them. A record's source, document section and namespace remain available in the response.
The unchanged 24-case offline suite now passes 24/24. It covers keyword recall, Chinese queries, conflicting evidence, access boundaries, no-answer queries and the real MCP transport. It does not measure semantic-model or generated-answer quality.
Try it without API keys
Requires Python 3.10+ and Git. The offline example works on Windows too (python can replace python3). The ingestion workflow below also needs Bash; use Linux, macOS or WSL for that path.
git clone https://github.com/Hidicence/x-knowledge-base.git
cd x-knowledge-base
python3 scripts/xkb_eval.py
This creates a temporary fixture library, starts real MCP subprocesses, runs the labelled queries and prints a JSON report. It uses no provider credentials and does not read your personal library.
Build your library
Create a data directory outside the checkout. xkb_init.py records its location; it does not create the directory for you.
Configure a chat-completions provider to generate cards. These commands send the selected notes to that provider and may incur costs. Use your own provider's URL, key and model name.
To send card generation and relevance judging to different providers, set XKB_GENERATION_API_URL/_API_KEY/_MODEL and XKB_JUDGE_API_URL/_API_KEY/_MODEL instead; a route with its own URL or key never borrows the generic LLM_* credentials. See .env.example.
Local ingestion writes both cards and the search index; a separate index rebuild is unnecessary here. Its exit code is 2 when new cards were added, 0 when none were added. That is a change signal, not a failure.
Keyword recall works without embeddings. Enable semantic retrieval using the embedding configuration guide; installing NumPy makes wiki similarity search much faster, with identical results when it is absent. Jev relevance judging is optional and requires a provider that also serves /systemone; a chat-completions endpoint alone is insufficient. An unavailable judge is reported and retains candidates. Set XKB_JEV_DECIDE=0 to disable it deliberately.
To generate an answer from the recalled evidence:
python3 scripts/xkb_ask.py "What is the difference between RAG and agent memory?"
The answer requires the configured chat model. --json includes the recall packet and available evidence references; it does not prove the model used every reference. The current answer prompt is tailored to Traditional Chinese.
Connect your agents
MCP provides recall. Conversation capture needs a separate hook or HTTP integration. Connecting an MCP tool does not automatically record every conversation.
For an MCP client such as Codex or Claude Code, register this stdio server, using absolute paths:
This is the common JSON configuration shape; translate it to your client's configuration format. The tool is xkb_recall, with message and optional limit arguments. Restart or reconnect the client after changing its configuration.
For a local library, the private environment file can contain:
To share one deployed library across machines, run python3 scripts/xkb_knowledge_service.py on the host holding your data. Point clients at that service instead:
Keep keys outside the repository. Configure server-side tokens as described in the service guide; the namespace must match the token. For another machine, use HTTPS or an SSH tunnel, for example ssh -N -L 18972:127.0.0.1:18972 your-server.
Integration
What it provides
MCP clients
On-demand recall through xkb_recall.
HTTP clients / OpenClaw integrations
Recall, plus explicit session and turn capture through the service API.
Claude Code hook installer
UserPromptSubmit recall and Stop capture after installation. Scheduled claude -p runs (marked unattended by Claude Code) are skipped.
python3 scripts/xkb_install_agent_hook.py --install targets Claude Code settings. It does not install a Codex/Orca hook. Configure its service connection separately; MCP settings are not hook settings.
Check the actual connection with a topic in your library:
Doctor verifies MCP initialization, tool discovery and a real call. ready, degraded and failed have different meanings. Add --require-semantic --require-judge to require those capabilities. See recall validation for full configuration and diagnostics.
How recall works
Read the allowed sources. Cards, wiki/daily-note sections and captured conversation traces retain their provenance. Namespace and visibility rules apply before evidence is returned.
Retrieve candidates. Configured semantic backends search cards and wiki; keyword fallback remains available. Conversation traces use keyword retrieval.
Check relevance. When configured, Jev judges whether each candidate answers the query. A failed or missing verdict is not counted as rejection.
Merge and rank. Evidence identity includes namespace and, for documents, section. Different sections remain distinct; duplicate retrieval paths do not inflate usage counts.
Return an inspectable packet. Records, source references, search mode, per-source status, judge status and warnings travel together through MCP, HTTP and the default CLIs.
Choose what to bring up unasked. The packet's delivery holds at most three judged-relevant items, reusable knowledge (cards, wiki) first; past conversations and daily notes take at most one slot, and only when strongly relevant. No generation model is called for this: the agent answering the turn already sees the whole conversation and decides whether a suggestion applies. Within a captured session, items already suggested since Claude Code last compacted it, and the session's own recent traces, are not offered again; an edited wiki section or note can be.
Repeated explicit negative verdicts can lower an item's rank. Demotion never deletes the source; one positive verdict lifts it. Returned evidence, judged relevance and use in a final answer are different events.
The older continuity/associative/contrarian/action presentation remains available via recall_router.py --legacy-router. It is not the default shared recall path.
From sources to durable knowledge
XKB also includes ingestion adapters for local notes, X bookmarks, YouTube transcripts, GitHub repositories and papers. They produce a shared nine-section card format with source links, claim levels and summaries; image-bearing sources can add OCR and vision evidence.
Cards can be consolidated into wiki topics through the absorption workflow. Captured conversations can be staged as candidates for review. Recall itself never promotes a conversation into wiki knowledge. Run and review these write workflows separately; see the command guide and wiki schema.
Boundaries worth knowing
Local-first describes storage and control. Cloud card generation, embeddings, relevance judging and answer generation send their respective inputs to configured providers. Selecting local embeddings alone does not make the whole system offline.
Fallback is visible. A missing judge retains candidates and reports degradation. An explicitly configured remote service failure is an error; it never silently switches to a different local library.
Quality still needs your labels. The synthetic suite is a regression check. Judge thresholds and semantic retrieval need evaluation on independently reviewed examples from your own library.
This is a self-hosted toolset. Source adapters have their own dependencies. Hybrid XBrain/GBrain search requires its backend; it is not needed for the offline example or keyword recall.
PolyForm Noncommercial 1.0.0. Noncommercial use is permitted under its terms; commercial use requires separate permission.
X
X Knowledge Base
Hidicence·12 étoiles·
Self-hosted knowledge for AI agents that brings relevant notes, cards and past conversations into an ongoing chat, even when nobody asked. One shared MCP/HTTP recall service; sources stay as linked Ma
Self-hosted knowledge for AI agents that brings relevant notes, cards and past conversations into an ongoing chat, even when nobody asked. One shared MCP/HTTP recall service; sources stay as linked Markdown you control.
Outils
Outils
Pas encore de liste d'outils. Les serveurs distants en obtiennent une après le premier contrôle d'état.
FAQ
Questions
Comment installer X Knowledge Base ?
Copiez sur cette page la configuration stdio pour Cursor, Claude Desktop, Claude Code ou VS Code. Elle utilise l'installation de l'éditeur, pas un proxy PlugMCP.
Aucune variable d'environnement requise n'est indiquée sur cette fiche.
Quel transport X Knowledge Base utilise-t-il ?
X Knowledge Base s'exécute en local via stdio.
Quand X Knowledge Base a-t-il été vérifié pour la dernière fois ?
Dernière vérification : 2026-10-28. Self-hosted knowledge for AI agents that brings relevant notes, cards and past conversations into an ongoing chat, even when nobody asked. One shared MCP/HTTP recall service; sources stay as linked Markdown you control.
