2.7 KiB
Project North Star: KB
KB is a local-first, multi-project knowledge base for people and AI agents. It turns collected sources into scoped, evidence-backed notes and linked syntheses that remain traceable, reviewable, and reusable across projects and tools.
Core Mission
Help project teams find and reuse trustworthy knowledge without losing its source, scope, freshness, or uncertainty. People can explore and curate the knowledge through a web UI; agents can retrieve cited, budgeted results through typed MCP and HTTP interfaces, and contribute only through validated proposals.
Invariant Non-Negotiables
- Evidence before assertion: Every claim and datapoint must trace to a source and a quote location. Validation checks the evidence against the archived source when available; unsupported interpretations remain clearly identified as interpretations.
- Project scope is explicit: Every node belongs to one registered project or the shared library. Cross-project relevance is represented through explicit typed links and project-specific lens fit, never by silently copying or blending project knowledge.
- Humans own project intent: Project owners control the north star, key questions, and autonomy policy. Agents can propose changes, but cannot directly change those human-owned goals.
- Proposals are the write boundary: Agents submit changes to staging. Shared validators enforce schemas, scope, link rules, and evidence requirements before a proposal can be accepted into the knowledge base.
- Git files are the source of truth: Markdown and YAML records remain directly inspectable and versioned. Search indexes are derived, disposable, and rebuildable from those files.
- One core, multiple interfaces: The UI, CLI, MCP server, and HTTP API use the same scoped service and validation rules. No interface grants agents a privileged write path or exposes raw database queries.
- Trust survives change: Preserve history and audit records; link contradictions instead of overwriting them; retain superseded knowledge; and disclose staleness whenever dated information is retrieved.
- Local-first and agent-agnostic: The system remains useful with local files and local models, runs across Windows, macOS, and Linux, and does not depend on any one agent harness or vendor integration.
Definition of Success
A person or agent can answer a project question with a useful, cited result in the intended time and token budget; merged claims have valid evidence; stale datapoints carry warnings; and knowledge can be reused across projects without losing its origin or confusing its scope. The measurable v1 targets are maintained in the PRD.