pyrite-wiki/pyrite

**A second brain for you, your agents, and your teams.**
Knowledge-as-Code — structured knowledge in markdown files with YAML frontmatter, schema-validated, versioned in git, searchable by any AI through MCP.
Your AI agents have no memory. Your knowledge is trapped in platform silos. Every new chat starts from zero. Pyrite gives you structured, validated, git-versioned knowledge bases that any AI can read and write through a built-in MCP server. One brain, every AI, persistent memory that compounds over time.
**Why Pyrite instead of vectors-in-Postgres or Notion+AI?**
- **Typed entries with schema validation** — not flat vector blobs. Define person, decision, event, component types with validated fields. Query structurally, not just by vibes.
- **Git-native** — every change is a versioned commit, not a database mutation. Branch, diff, review, rollback. Your knowledge has a full audit trail.
- **MCP server with three-tier access control** — read/write/admin tiers. Give untrusted agents read-only access. Give your own agents write access. Keep admin for yourself.
- **Semantic + structured search** — find by meaning (vector embeddings) AND by type, tag, date range, or relationship. Both at once in hybrid mode.
- **Plugin system with 19 extension points** — custom entry types, MCP tools, CLI commands, validators, lifecycle hooks, relationship semantics, schema migrations.
- **Zero running cost locally** — markdown files + SQLite index on your disk. No cloud dependency, no subscription, no vendor lock-in. Your data is plain text files you can read in any editor.
> **Multi-user is experimental. Here be dragons.** Pyrite is solid for one person, their agents, and a team that trusts each other. Accounts, per-KB permissions and the public /site work, and each release closes more gaps, but they have not had the review a system holding other people's private data needs. Don't put knowledge on a shared or internet-facing instance that you couldn't live with every user of that instance reading. See SECURITY.md.
Quick Start
pyrite mcp-setup points a pyrite server entry at this install where each
client reads it: claude mcp add -s user for Claude Code (or ./.mcp.json
with --project), and Claude Desktop's own claude_desktop_config.json. Run it
again any time. An entry that already points here is not rewritten; one that
points elsewhere gets its command path changed (and its tier, if you pass
--tier), and keeps its env, extra arguments and other keys. Other servers
are never touched. Each client is all or nothing: one it cannot change safely
is left as it was with the reason, while another may still be changed, and
the exit code is 1 unless every client ended up pointing here. The JSON report
names each client and what changed, says what the file holds when a change
could not be finished, and names a pyrite entry in another Claude Code scope
(one project's, from claude mcp add without -s user) that would be used
instead of this one.
Getting started lists the
cases.
Or add it by hand to any MCP client's config:
Use the absolute path (which pyrite): Claude Desktop does not see your shell's
PATH or an activated venv.
Now any AI that speaks MCP can search, read, and write your knowledge base.
How It Works
Markdown files with YAML frontmatter in git are the source of truth. Pyrite builds a SQLite FTS5 index (with optional vector embeddings) on top of the files for fast search. The MCP server, CLI, and REST API all read from and write to the same files. Rebuild the index from files at any time with pyrite index build.
You define domain-specific entry types and field schemas in a kb.yaml file. Pyrite validates entries on every write, indexes them, and exposes them through all interfaces. A plugin protocol lets you extend entry types, add MCP tools, define relationship semantics, and hook into lifecycle events.
MCP Server
Three permission tiers. Each tier includes the tools from lower tiers. Counts below are the core kb_*/task_* tools only; installed plugins add more per tier (e.g. software-kb adds sw_adrs, sw_backlog, sw_new_adr) — run pyrite mcp --help for the live total including plugin tools, generated from the tool registry so it can't drift from what a running server exposes.