project-kb 1.0.1

A local, evidence-first project knowledge base with a Windows MCP server and CLI. It stores source snapshots and summaries in SQLite, retains provenance, and exposes bounded local search and exact readback. This public distribution has no external model API integration.

This source release contains code only. Runtime databases, vault content, local settings, credentials, logs, and source projects belong outside Git history. The production schema-3 deployment is Windows-specific. This release was tested on Python 3.11. Read the 1.0.1 audit and release notes before deploying it.

Try It With An Isolated Sample

Run these commands from a PowerShell session in this checkout. They create only ignored .local data. Use a disposable sample project inside .local\sources. The ranking byte ceiling is an explicit local storage limit, not a usage target.

py -3.11 -m venv .venv
& .\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
& .\.venv\Scripts\python.exe -m pytest -q tests
$repo = (Get-Location).Path
$env:PROJECT_KB_PROFILE = 'sandbox'
$env:PROJECT_KB_SANDBOX_BASE = $repo
$env:PROJECT_KB_ROOT = Join-Path $repo '.local\kb'
$env:PROJECT_KB_SOURCE_ROOT = Join-Path $repo '.local\sources'
$env:PROJECT_KB_PUBLIC_V2 = '1'
$env:PROJECT_KB_ENABLE_SANDBOX_WRITES = '1'
$env:PROJECT_KB_RANK_MAX_BYTES = '67108864'
New-Item -ItemType Directory -Path "$env:PROJECT_KB_ROOT\indexes", "$env:PROJECT_KB_SOURCE_ROOT\sample" -Force | Out-Null
Set-Content -LiteralPath "$env:PROJECT_KB_SOURCE_ROOT\sample\README.md" -Value 'A sample calibration checklist.'
& .\.venv\Scripts\python.exe scripts\kb_v2.py init
& .\.venv\Scripts\python.exe scripts\kb_v2.py init-api --operation-id sample-init-api
& .\.venv\Scripts\python.exe scripts\kb_v2.py register-root --operation-id sample-register --project-id sample --root "$env:PROJECT_KB_SOURCE_ROOT\sample"
& .\.venv\Scripts\python.exe scripts\kb_v2.py rank-install --operation-id sample-rank
& .\.venv\Scripts\python.exe scripts\kb_v2.py refresh --operation-id sample-refresh --project-id sample --root "$env:PROJECT_KB_SOURCE_ROOT\sample"
& .\.venv\Scripts\python.exe scripts\kb_v2.py search calibration --project-id sample

Operation IDs are idempotency keys. Reuse one only for an identical retry. Keep PROJECT_KB_ENABLE_SANDBOX_WRITES unset for read-only sessions. The sample does not turn a new checkout into an existing production deployment.

Start the MCP server from the same configured environment with & .\.venv\Scripts\python.exe -B -X utf8 -u .\mcp_server.py. The server exposes compact kb_retrieve and exact kb2_* interfaces; source summaries remain evidence candidates until independently checked.

Related MCP server: agent-fact-system

Existing Production Store

An existing schema-3 installation has a deployment.json marker and an active indexes/kb-v3.sqlite. By default, production code expects that installation at $HOME\project-kb and source repositories at $HOME\git. Set PROJECT_KB_INSTALL_ROOT and PROJECT_KB_SOURCE_ROOT before starting the server when those paths differ. Keep the production data and code together at the configured installation root. See local settings.

Search remains local. No query or indexed evidence is sent to an external model service by this code. The local MCP interface and versioned kb2_* commands remain available.

Before GitHub

Run python scripts\check_public_tree.py and inspect git status --short. The check examines both Git's staged bytes and current worktree files. It reports possible leaks by path and line number without printing matched text. It cannot prove that every project document is licensed for publication. After review, run python scripts\build_release.py to create the source ZIP under the ignored .local\dist directory. The build refuses mismatched staged and worktree bytes; it does not commit or push the repository.

License

This is source-available software, not an open-source license. Individuals and organizations may download, install, and run the unmodified code for their own internal purposes, including commercial internal use. Modification, redistribution, and public hosting require separate written permission. Read the complete LICENSE.md before use. GitHub's platform terms still allow viewing and forking a public repository.

The release does not upload anything automatically. Review and test details are in RELEASE_1.0.1.md. See SECURITY.md for the SSH, MCP and data boundaries.