# 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

1. **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.
2. **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.
3. **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.
4. **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.
5. **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.
6. **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.
7. **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.
8. **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](PRD.md#success-metrics).