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.

# Install (no PyPI wheel yet -- from source)
git clone https://github.com/markramm/pyrite.git && cd pyrite
pip install -e ".[all]"

# Initialize a knowledge base
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

# Connect to Claude Desktop / Claude Code
# Add to your MCP config:

{
  "mcpServers": {
    "pyrite": {
      "command": "pyrite",
      "args": ["mcp"]
    }
  }
}

Now any AI that speaks MCP can search, read, and write your knowledge base.

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

Three permission tiers. Each tier includes the tools from lower tiers.

All paginated tools (kb_search, kb_timeline, kb_backlinks, kb_tags) support limit/offset params and return a has_more flag. kb_bulk_create handles up to 50 entries per call with best-effort per-entry semantics. kb_orient provides a one-shot KB summary for agent onboarding. kb_batch_read fetches multiple entries in one call. Search results return snippets by default (use include_body for full text, fields for projection).

Plugins add their own tools per tier (e.g., software-kb adds sw_adrs, sw_backlog, sw_new_adr).

Also exposes: 4 prompts (research_topic, summarize_entry, find_connections, daily_briefing), resources (pyrite://kbs, pyrite://kbs/{name}/entries, pyrite://entries/{id}).

Use pyrite mcp --tier read for a read-only server.

# Search (keyword, semantic, or hybrid)
pyrite search "immigration policy"
pyrite search "immigration" --kb=timeline --type=event --mode=hybrid

# Read
pyrite get stephen-miller
pyrite backlinks stephen-miller --kb=research
pyrite timeline --from=2025-01-01 --to=2025-06-30
pyrite collections list --kb=research

# Write
pyrite create --kb=research --type=person --title="Jane Doe" \
  --body="Senior policy advisor." --tags="policy,doj"

# Admin
pyrite index sync          # Incremental re-index after file edits
pyrite index health        # Check for stale/missing entries
pyrite kb discover         # Auto-find KBs by kb.yaml presence

# Schema versioning
pyrite schema diff --kb=research      # Show type versions and field annotations
pyrite schema migrate --kb=research   # Migrate entries to current schema version

All commands support --format json for agent consumption.

Define types in kb.yaml:

name: legal-research
kb_type: generic
types:
  case:
    description: "Legal case or proceeding"
    fields:
      jurisdiction:
        type: select
        options: [federal, state, international]
      status:
        type: select
        options: [active, decided, appealed, settled]
      filing_date:
        type: date
      parties:
        type: list
        items:
          type: text

Types support versioning for safe schema evolution:

types:
  case:
    version: 2
    fields:
      methodology:
        type: text
        required: true
        since_version: 2  # required for new entries, warning-only for legacy

Entries track their schema version in _schema_version frontmatter. pyrite schema migrate applies registered migrations and produces a reviewable git diff.

Field types: text, number, date, datetime, checkbox, select, multi-select, object-ref, list, tags.

Ten built-in entry types: note, person, organization, event, document, topic, relationship, timeline, collection, qa_assessment. Entries support aliases for alternate names that resolve in wikilinks and autocomplete.

Extensions implement a Python protocol class with up to 19 methods:

• get_entry_classes() — custom entry types with serialization
• get_type_metadata() — field definitions, AI instructions, presets
• get_collection_types() — custom collection types
• get_mcp_tools(tier) — per-tier MCP tools
• get_cli_app() — Typer sub-commands
• get_validators() — entry validation rules
• get_migrations() — schema migration functions for entry type upgrades
• get_relationship_types() — semantic relationship definitions
• Lifecycle hooks: before_save, after_save, before_delete, after_delete

Six extensions ship:

Optional SvelteKit 2 + Svelte 5 frontend for browsing, visualization, and oversight:

• WYSIWYG + markdown editor (Tiptap + CodeMirror dual mode)
• [[wikilinks]] with autocomplete, alias resolution, and pill decorations
• ![[transclusion]] embedded content cards
• Block references: [[entry#heading]] and [[entry^block-id]]
• Backlinks panel, outline/TOC, split panes
• Interactive knowledge graph (Cytoscape.js)
• Collections with list, table, kanban, and gallery views
• Virtual collections via query DSL
• AI chat sidebar (RAG), summarize, auto-tag, suggest links
• Quick switcher (Cmd+O), command palette (Cmd+K)
• Daily notes with calendar
• Timeline visualization
• Version history with diff viewer
• Web clipper for URL content capture
• WebSocket multi-tab sync
• Slash commands in editor

pyrite/
├── models/          # Entry types (base, core_types, factory, generic, collection)
├── schema.py        # YAML-driven type definitions, field validation
├── migrations.py    # Schema migration registry (on-load entry transforms)
├── config.py        # Multi-KB and repo configuration
├── server/
│   ├── api.py       # FastAPI REST API factory (role-based tier enforcement)
│   ├── mcp_server.py # MCP server (mcp SDK, 3-tier, paginated)
│   ├── websocket.py # WebSocket multi-tab sync
│   └── endpoints/   # Per-feature REST routes (entries, search, kbs, collections, graph, daily, clipper, ...)
├── storage/
│   ├── database.py  # SQLite + FTS5 + sqlite-vec (SQLAlchemy ORM + raw SQL)
│   ├── index.py     # Incremental indexing with wikilink/transclusion extraction
│   └── repository.py # Markdown file I/O
├── services/        # Business logic (kb, search, embedding, llm, git, collection_query, clipper, user)
├── plugins/         # Plugin discovery and protocol
└── formats/         # Content negotiation (JSON, Markdown, CSV, YAML)

extensions/          # Domain-specific plugins (software-kb, zettelkasten, encyclopedia, social, cascade, task)
web/                 # SvelteKit 2 + Svelte 5 frontend (TypeScript + Tailwind)
kb/                  # Pyrite's own KB (ADRs, backlog, components, standards)

Storage model: Markdown files in git are the source of truth. SQLite FTS5 is a derived index. Rebuild from files at any time with pyrite index build. Background embedding pipeline keeps vector index current.

Content negotiation: REST API responds in JSON, Markdown, CSV, or YAML via Accept header. CLI supports --format.

Access control: REST API supports role-based tier enforcement (read/write/admin) with hashed API keys.

Fly.io — create a volume and deploy:

fly launch --copy-config --name my-pyrite
fly volumes create pyrite_data --size 1
fly deploy

All three platforms use the included Dockerfile, persist data at /data, and expose port 8088. Set PYRITE_AUTH_ENABLED, PYRITE_OPENAI_API_KEY, and other env vars in your platform's dashboard after deploy.

Run your own Pyrite instance on any VPS ($6/month, unlimited users, you own your data):

git clone https://github.com/markramm/pyrite.git && cd pyrite
bash deploy/selfhost/setup.sh kb.example.com

This installs Docker, starts Pyrite + Caddy (auto TLS), and seeds Pyrite's own KB so you have content to explore immediately. Then create your admin user:

docker compose -f deploy/selfhost/docker-compose.yml exec pyrite \
  python /app/deploy/selfhost/create-user.py admin yourpassword

Auth is required, registration is closed by default — add users manually with the same command.

For local development without TLS, use the minimal compose:

docker compose up -d  # http://localhost:8088

No PyPI wheel yet — install from source:

git clone https://github.com/markramm/pyrite.git && cd pyrite
pip install -e ".[all]"      # Core + AI + semantic search + dev tools

Narrower extras: pip install -e ".[server]" (REST API + web UI), pip install -e ".[ai]" (OpenAI + Anthropic SDKs), pip install -e ".[semantic]" (sentence-transformers + sqlite-vec).

Extensions are installed separately:

pip install -e extensions/software-kb
pip install -e extensions/zettelkasten
pip install -e extensions/encyclopedia
pip install -e extensions/social
pip install -e extensions/cascade
pip install -e extensions/journalism-investigation

Prefer not to install anything locally? See Deploy above for Docker, one-click cloud (Railway/Render/Fly.io), and self-hosted VPS options — or pyrite.wiki for a hosted instance.

python -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"
for ext in extensions/*/; do pip install -e "$ext"; done
pre-commit install

# Tests (~2500 tests)
pytest tests/ -v

# Frontend
cd web && npm install && npm run dev

# Linting
ruff check pyrite/

Pyrite's own backlog and architecture docs live in kb/:

pyrite sw backlog        # Prioritized backlog
pyrite sw adrs           # Architecture Decision Records (22 ADRs)
pyrite sw components     # Module documentation
pyrite sw standards      # Coding conventions

• Getting Started — install, create a KB, connect an AI
• Plugin Writing Tutorial — build a custom plugin step by step
• Plugins Directory — official and community plugins
• OpenAI / Codex MCP Integration
• Gemini CLI MCP Integration

Pyrite was built at Transparency Cascade Press, an independent investigative outfit, because the reporting needed it. Investigations there run on thousands of sourced entries — actors, events, contracts, court filings — that have to stay verifiable months after they were written, and no note-taking tool treated an AI research assistant as a first-class user of that record rather than a chat window bolted onto it.

That constraint shaped the design. Agents are users here: they create and query entries through the CLI and MCP, they get typed errors instead of tracebacks, and they operate under the same schema validation and three-tier permissions a human does. The knowledge base is plain markdown in git precisely so a claim can be traced to the commit that introduced it, which is a journalism requirement before it is a software one.

It is still used in production for that work, and it has since grown past it into a general tool.

Started as a fork of joshylchen/zettelkasten. Since substantially rewritten: multi-KB, plugin system, three-tier MCP, FTS5 + vector search, REST API with tier enforcement, SvelteKit frontend, service layer, schema-as-config, content negotiation, collections, block references, web clipper, AI integration. See UPSTREAM_CHANGES.md for divergence history.

MIT — see LICENSE.