Skip to main content
Glama

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

knowlageMCP-gateway

Host

Service lifecycle, SQLite database (single writer), identity registry, policy, FTS5 search, review queue, HTTP/MCP endpoints, Unix admin socket

knowlageMCP-gatewayctl

Host

Bootstrap assistance, status, approvals, namespaces/grants, inspect/correct/forget, backup/restore, diagnostics

knowlageMCP-mcp

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, and pipx (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 --bootstrap

The 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-interactive

Optional 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-test

status 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-gateway

Stop 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 doctor on 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 shared

Replace 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 SESSION

Approval 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.

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 reindex

The 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-test

Expected 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 passed

Measured baseline

See docs/testing.md for the 2026-11-11 retrieval and latency baseline on the reference hardware.

Documentation and license

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 tools
delegate_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

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

    C2.9/5.0

    Scored across 16 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Gives 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
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -