knowlageMCP
The server is an MCP knowledge gateway where AI agents register, store, retrieve, search, revise, and review scoped provenance-tracked knowledge, with optional mentor enrollment and evidence upload.
Get protocol/schema versions and the packaged usage skill.
Register agents, delegate single-use child tickets, request or poll mentor enrollment, and close sessions.
Retrieve a budgeted task context bundle and search authorized namespaces with filters, cursors, and byte/result limits.
Read entries and revisions; record typed candidate entries with scope, sources, evidence, provenance, lifecycle, and idempotency.
Propose corrections using optimistic concurrency and record task outcomes linked to used revisions.
Lease queued review items and submit review results with evidence, method, limitations, and evidence class.
Upload bounded text evidence objects without filesystem paths.
Host operators can use gatewayctl for bootstrap/status, approvals, namespaces/grants, inspect/correct/forget, backup/restore, and diagnostics.
Optional embedding provider used for semantic/hybrid search over stored knowledge entries. When enabled (off by default), the gateway calls an OpenAI-style embeddings endpoint to vectorize entries, which are then indexed alongside lexical FTS5 search to improve retrieval; the core runs fully without it.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@knowlageMCP retrieve the relevant knowledge bundle before I start this task"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
knowlageMCP
knowlageMCP is a host-owned knowledge service for AI coding agents that run in terok containers. Agents register themselves through MCP and store scoped, provenance-tracked entries (preferences, instructions, decisions, observations, hypotheses, procedures, failures, task summaries). At task start they retrieve a small, budgeted bundle of relevant entries instead of replaying history. An operator on the host administers everything through a CLI, and an optional externally started AI mentor reviews candidate entries after manual approval. All canonical data (SQLite database, evidence files, backups) stays on the host; the container sees only a small HTTP/MCP surface. The core runs without API keys, embeddings, a mentor, or any external service.
Components
Executable | Runs on | Responsibility |
| Host | Service lifecycle, SQLite database (single writer), identity registry, policy, FTS5 search, review queue, HTTP/MCP endpoints, Unix admin socket |
| Host | Bootstrap assistance, status, approvals, namespaces/grants, inspect/correct/forget, backup/restore, diagnostics |
| Agent environment | Stdio MCP bridge; only the gateway host/port needs configuration |
Related MCP server: io.github.cdnsteve/sugar
Requirements
Linux host, Python 3.11 or newer (tested on 3.11, 3.12, 3.13 and 3.14),
git, andpipx(or a virtualenv).SQLite with FTS5 (standard in current system SQLite builds).
For container access: terok network access to the host service, or a manually reachable host port. See the note under "Agent setup".
Publication to PyPI is not part of this release. Install from the git URL or a local clone. The repository may carry an unreleased 0.1.0 version.
Host setup
Host terminal 1 (the machine that will keep the database):
git clone https://github.com/psychocoderHPC-bot/knowlageMCP.git
cd knowlageMCP
pipx install .
knowlageMCP-gateway --bootstrapThe wizard asks a few questions, all with usable defaults, then writes the config, creates private data directories, and initializes the database. In CI or scripts use:
knowlageMCP-gateway --bootstrap --non-interactiveOptional overrides: --host, --port, --database, --evidence-dir,
--backup-dir, --no-systemd, --start / --no-start, --force.
Host terminal 2 (same machine; the gateway must be running):
knowlageMCP-gatewayctl status
knowlageMCP-gatewayctl smoke-teststatus prints version, schema version, listener, session and agent counts.
smoke-test exercises health, registration, a record, and a search against a
live service and prints the steps it ran.
Run as a systemd user service
The repository ships systemd/knowlage-mcp-gateway.service. Install and start
it with:
cp systemd/knowlage-mcp-gateway.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user start knowlage-mcp-gateway
systemctl --user status knowlage-mcp-gatewayStop with systemctl --user stop knowlage-mcp-gateway. The service starts
without a mentor and without API keys. Optionally, keep the service alive
after logout with loginctl enable-linger $USER; the unit does not enable
linger automatically.
Agent setup
Inside the agent container, install the bridge (only endpoint/port configuration is needed; registration itself happens through MCP):
pipx install "git+https://github.com/psychocoderHPC-bot/knowlageMCP.git"or clone the repository and run pipx install .. Then register the MCP server
in your client. OpenCode-style configuration (the bridge defaults the host to
host.containers.internal, which matches the terok host-service arrangement):
{
"mcp": {
"knowledge": {
"type": "local",
"command": ["knowlageMCP-mcp", "--port", "2230"],
"enabled": true
}
}
}Overrides, in precedence order: --url wins over --host/--port, which win
over the environment variables KNOWLAGEMCP_URL, KNOWLAGEMCP_HOST,
KNOWLAGEMCP_PORT. The defaults are host.containers.internal and port 2230.
This is the only manually configured connection information; after the client
connects, the agent calls the register_agent tool itself and no token is
ever copied by hand.
Validate the client's actual MCP schema against its own documentation; the block above is the intended shape, not a guarantee for every client.
Terok shield and container reachability
The container needs network permission to reach the gateway. In the terok project configuration:
shield:
allow:
- "localhost:2230"Two caveats:
Existing running tasks were started with the old shield rules and may need recreation before the new allow rule takes effect.
Binding a loopback port on the host does not automatically make it reachable from every container. If the bridge cannot connect, check
knowlageMCP-gatewayctl doctoron the host (it prints host/container connection hints) and verify the actual terok host-service forwarding for your container runtime.
Optional mentor approval
The mentor is any external AI session the operator starts manually with the
same bridge and the mentor skill (skills/knowlageMCP/mentor.md). It requests
enrollment through the request_mentor tool; the operator approves on the
host:
Host terminal:
knowlageMCP-gatewayctl enrollments
knowlageMCP-gatewayctl approve REQUEST --role mentor --ttl 2h --namespace sharedReplace REQUEST with the request ID shown by enrollments (or by watch);
the comparison code printed next to it is for operator verification only and
is not an approval credential. Deny or revoke at any time:
knowlageMCP-gatewayctl deny REQUEST
knowlageMCP-gatewayctl revoke SESSIONApproval is bound to the exact pending session and requested scopes, expires after the TTL, and is revocable. Without an approved mentor, all normal read/write work continues and reviews simply stay queued.
Optional semantic search
Hybrid search (lexical FTS5 plus a Qdrant vector index), a bounded reranker, and extraction adapters are optional and off by default. To enable a minimal setup in the config file:
[integrations]
enabled = true
[integrations.embedding]
provider = "openai"
base_url = "http://127.0.0.1:8080"
dimensions = 1536
[integrations.vector]
backend = "qdrant"
url = "http://127.0.0.1:6333"
vector_size = 1536
[integrations.reranker]
provider = "lexical"then rebuild the index once:
knowlageMCP-gatewayctl integrations reindexThe core runs fully without any of it: with integrations.enabled = false
search stays lexical, no network I/O happens, and no secrets are required.
Search remains fail-open when a backend is down. Details, operations, and
failure semantics are in docs/integrations.md.
Smoke test
With the gateway running and at least one agent container connected (the smoke test registers its own temporary agent), run on the host:
knowlageMCP-gatewayctl smoke-testExpected output (abridged; IDs are random):
health ok (protocol 1.0, schema 1)
register ok (agent_..., actor_...)
record ok (entry_...)
search ok (1 result)
close ok
smoke test passedMeasured baseline
See docs/testing.md for the 2026-11-11 retrieval and latency baseline on the reference hardware.
Documentation and license
docs/architecture.md - trust boundaries, flows, restart policy
docs/configuration.md - every config key and limit
docs/operations.md - bootstrap, CLI, backup, forgetting
docs/protocol.md - MCP tools, HTTP bridge API, errors
docs/data-model.md - tables, lifecycle, provenance
docs/testing.md - test layout, quality corpus, measured baseline, CI
docs/troubleshooting.md - symptom to fix
docs/mentor.md - mentor operating procedure
docs/integrations.md - adapter boundaries, JSONL format
docs/security-checklist.md - trust-boundary guarantees mapped to enforcement and regression tests
LICENSE (ISC), SECURITY.md, CONTRIBUTING.md
Limitations
Self-registration does not prove an independent person, model, or process; it is a convenience for a single-operator trusted environment.
A process can still register multiple identities; the system does not detect Sybil behaviour in general.
Backups live on the same disk and do not protect against disk loss.
There is no high availability, no multi-host SQLite, and no web dashboard.
Search is lexical (FTS5) by default. Semantic/hybrid search is an optional layer, off by default, and never mandatory (see "Optional semantic search").
Available Tools
16 toolsdelegate_childC
Issue a single-use child delegation ticket for this session.
Inputs: ttl, actor_handle. Returns: result
enrollment_statusC
Poll the state of your own mentor enrollment request.
Inputs: request_id (required), actor_handle. Returns: result
get_contextC
Return a small, budgeted task-relevant memory bundle.
Inputs: task, scope, actor_handle. Returns: result
get_entryC
Read one entry revision with history and a bounded detail page.
Inputs: entry_id (required), page, cursor, revision_id, +1 more. Returns: result
get_protocol_infoA
Return protocol, application, and schema versions with tool names.
Inputs: no named parameters. Returns: result
get_usage_skillC
Return the bounded packaged agent usage skill.
Inputs: no named parameters. Returns: result
propose_revisionC
Propose a correction using optimistic concurrency.
Inputs: entry (required), entry_id (required), expected_revision (required), actor_handle, +1 more. Returns: result
recordC
Record a typed candidate entry in a namespace you may write.
Inputs: entry (required), namespace (required), actor_handle, idempotency_key. Returns: result
record_outcomeC
Record a task outcome linked to revisions you used.
Inputs: outcome (required), notes, task_label, actor_handle, +2 more. Returns: result
register_agentC
Register this agent and return identity metadata; no token over MCP.
Inputs: mode, task, label, model, +2 more. Returns: result
request_mentorC
Request operator approval for a mentor grant on a namespace.
Inputs: namespace (required), scopes, actor_handle. Returns: result
review_nextC
Lease the next eligible review item for this session.
Inputs: filters, actor_handle. Returns: result
searchB
Search authorized namespaces with filters and a byte budget.
Inputs: query (required), cursor, filters, max_bytes, +2 more. Returns: result
session_closeC
Release leases and revoke the current session.
Inputs: all_actors, actor_handle. Returns: result
submit_reviewC
Submit evidence and a result for an exact leased revision.
Inputs: method (required), result (required), entry_id (required), revision_id (required), +8 more. Returns: result
upload_evidenceC
Store a bounded text evidence object; no filesystem paths.
Inputs: text (required), name, media_type, actor_handle. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools have clearly distinct purposes: search vs get_entry vs get_context differ by granularity, and record vs propose_revision differ by create vs correct. The only mild overlap is between upload_evidence and record (both persist text), and between request_mentor and enrollment_status, but the request/poll split is made clear in descriptions.
Most tools are verb-first (get_protocol_info, register_agent, propose_revision, upload_evidence), but conventions are mixed: bare verbs like 'search' and 'record', noun-first 'session_close', noun-only 'enrollment_status', and verb-adverb 'review_next'. Still readable, but no single predictable pattern.
At 16 tools it is slightly above the comfortable range, but the surface maps cleanly onto distinct lifecycle stages (identity, delegation, mentoring, memory CRUD, review, session teardown), so each tool roughly earns its place.
Covers registration, delegation, mentor enrollment polling, search/read/record/correct, review leasing and submission, evidence upload, and session close. Minor gaps remain: no forget/delete or retire-entry operation, no way to list authorized namespaces, and no visibility into pending delegations or mentor grants beyond your own enrollment.
Maintenance
Related MCP Connectors
Shared, scoped, reviewable team memory for AI coding agents.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Project memory, documentation and controlled secret access for AI coding agents.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceGives AI coding agents on-demand retrieval of workspace context, documentation, lessons, decisions and handoffs from a five-level (GLOBAL → WORKSPACE → PROJECT → FEATURE → SESSION) store, so they start with a small rule set instead of re-reading bloated docs. Exposes tools for dependency routing, knowledge search, doc reading and health checks backed by a zero-dependency SQLite + FTS5 memory with cross-project sharing of global-scoped knowledge.MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to read and write persistent local memory during sessions, storing and semantically searching project decisions, preferences, error patterns, guidelines, and cross-project standards from SQLite stores on the user's machine. An optional companion server also exposes an autonomous task queue for executing queued work.-
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to read and write persistent, local-first memory so project decisions, preferences, and cross-project guidelines survive across sessions and can be retrieved by semantic search. Optionally also exposes a task queue for autonomous execution that draws on the same stored context.-
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to store, search, and recall persistent project-scoped and cross-project context — decisions, preferences, error patterns, file notes, and guidelines — using local SQLite with semantic or keyword search and no external API calls. An optional companion task server in the same package lets agents pick up queued work and execute it autonomously using that accumulated memory.-