kickside/knowledge

Knowledge bases for the Kickside engine — KB registry, the document/graph engine contract, ingestion/injection workers, concept-graph enrichment, and a user-facing CRUD API.

What it owns

• Contracts (kickside.knowledge:*)
  • knowledge_bases — the global registry that creates/finds/lists/deletes KBs as components and manages their feed sources, with rollback metadata on reversible operations.
• Registry — the canonical binding for knowledge_bases.
• Lifecycle ownership — every KB deletion goes through knowledge_bases, which tears down each engine store before removing the component. Higher-level packages may reference a KB, but they do not own or intercept its lifecycle.
• Engine seam — the model-agnostic kb_store_lifecycle contract that the knowledge control plane uses to create/read/update/delete a KB engine's per-component store row. Node/edge/embedding/summary/graph operations never cross this seam — they are the engine's own internal concern (kb10's node_store). kb10 owns the kb10_* schema and binds the lifecycle contract.
• Workers — ingestion/injection (injection). Concept-graph enrichment, digest, and node/graph reading moved to the kb10 engine with the store split.
• Agent surface — KB memory recall, query/ingest tools, a Knowledge Manager trait for engine discovery and KB lifecycle, and a wippy.agent:memory binding (agent, traits). The Knowledge Manager tool is available through that trait in agent chat. It intentionally declares no MCP scopes, so Keeper's strict MCP dispatcher does not expose it to non-root MCP sessions.
• HTTP API — list/create/get/update/delete KBs, share + list access, ingest content/url, delete content by external identity, upload tokens, and search.

Authorization

Handlers perform no authentication or coarse authorization. The host mounts the endpoints on a router with token_auth + endpoint_firewall; the firewall enforces the endpoint capability and returns 401/403. In-code checks use the runtime primitives only: component.validate_access(id, component.ACCESS.*) for per-KB domain access, and the published kickside.users.persist:user_repo seam for the share user-existence check. The access-listing endpoint reads component_access directly via kickside.component.persist:component_reader.

Dependencies

• kickside/component — KBs are components; lifecycle, meta, access context, and the component reader all flow through kickside.component:*.
• kickside/uploads — document ingestion + upload tokens.
• wippy/dataflow — injection + enrichment dataflows.
• wippy/agent, wippy/llm — agent context/memory binding and embedding + extraction models.
• kickside/contract — the embeddable / queryable / deletable / content_provider contracts the KB provider bindings implement.

The module persists KBs as components through kickside.component; engine-owned storage remains behind each engine's contracts. Its HTTP endpoints attach to the required api_router, which must enforce auth + endpoint_firewall.

Adding a KB engine

Add one registry.entry with meta.type = kickside.kb_engine per public kb_type. The entry is the routing contract: declare impl_id, query_binding, store_contract, optional materializer_contract, UI tags, stats labels, and default config there. The knowledge control plane resolves create, read/list, query, delete, and source projection from that descriptor instead of branching on engine names.

Engines that want durable content ingestion bind the declared materializer contract and implement replace_document plus delete-by-external-id. Public content writes still go through the KB-owned thread; the materializer is only the projection of canonical thread events into engine storage.