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 file you commit to git (git commit or pyrite kb commit), not a database mutation. Branch, diff, review, rollback. Your knowledge has a full audit trail. In 0.26, Your files, exactly means an edit changes only what you asked; hand-maintained comments, order and quoting survive. See how Pyrite edits your files.
• 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 and per-KB permissions 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

# Install (no PyPI wheel yet -- from source). Needs Python 3.11+.
git clone https://github.com/pyrite-wiki/pyrite.git && cd pyrite
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"

# Initialize a knowledge base outside the clone
pyrite init --template research --path ~/my-kb

# Create some entries
pyrite create -k my-kb --type person --title "Sarah Chen" \
  --body "Engineering lead. Considering move to consulting." --tags "team,engineering"

pyrite create -k my-kb --type note --title "Switch to async standups" \
  --body "Decided 2026-03-01. Reduces meeting load by 3hrs/week." --tags "process"

# Search (keyword, semantic, or hybrid)
pyrite search "consulting" -k my-kb
pyrite search "career transition" -k my-kb --mode=semantic  # keyword mode finds exact words only
# The first semantic search downloads the embedding model (~90 MB, one time).
# Writes never wait on that download: an entry is keyword-searchable the
# moment it is written, and gets its embedding on the next `pyrite index
# embed` / `index sync` (or, on a server, at startup). Run `pyrite index
# embed` to fetch the model and catch up on demand.

# Connect to Claude Code and Claude Desktop (every client it finds; restart it after)
pyrite mcp-setup                  # write tier; --tier read|admin, --client, --project

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:

{
  "mcpServers": {
    "pyrite": {
      "command": "/absolute/path/to/.venv/bin/pyrite",
      "args": ["mcp", "--tier", "write"]
    }
  }
}

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.

Your files (git)  →  SQLite index (derived)  →  MCP server / CLI / REST API / Web UI
                                               ↑
                                          Any AI connects here

This is the beginning of the README. Read the rest at the original. Read the full README ↗