Knowledge Base Overview

The knowledge base is how Pontius learns your email patterns. Contacts, templates, rules, patterns, and policies combine to make your AI assistant smarter over time.

What is the Knowledge Base?

The knowledge base is an organized folder structure that stores everything the AI needs to know about handling your email effectively:

Blitz: Session preferences (sign-off, tone, delegation)
Contacts: Who people are and how to communicate with them
Templates: Pre-written responses for common situations
Rules: Per-account defaults and behaviors
Policies: Business guardrails (what to never do)
Patterns: Automated actions triggered by email content
Invoices: Company presets and invoice history
Campaigns: Outbound email sequences

Location

Your knowledge base lives at:

~/.config/pontius/knowledge/
├── README.md               # Overview for AI + humans
├── blitz/
│   ├── README.md           # How blitz preferences work
│   └── preferences.json    # Session prefs: sign-off, tone, delegation
├── contacts/
│   ├── README.md           # How contacts work
│   └── contacts.json       # Contact intelligence database
├── templates/
│   ├── README.md           # How templates work
│   ├── support.json        # Support response templates
│   ├── sales.json          # Sales/outbound templates
│   ├── operations.json     # Billing, invoices, vendors
│   └── custom.json         # Your custom templates
├── rules/
│   ├── README.md           # How rules work
│   └── accounts.json       # Per-account behavior settings
├── policies/
│   ├── README.md           # How policies work
│   └── policies.json       # Business guardrails
├── patterns/
│   ├── README.md           # How patterns work
│   └── patterns.json       # Action triggers
├── history/
│   ├── README.md           # How history works
│   └── history.json        # Interaction log (auto-populated)
├── invoices/
│   ├── README.md           # Invoice setup guide
│   ├── companies.json      # Company presets
│   └── logos/              # Company logos (PNG/JPG)
└── campaigns/              # Outbound email campaigns
    ├── README.md           # How campaigns work
    └── your-campaign/      # Each campaign is a folder

Setting Up the Knowledge Base

Initialize the knowledge base folder structure:

$ pontius knowledge init
Creating knowledge base structure...
  ✓ ~/.config/pontius/knowledge/blitz/
  ✓ ~/.config/pontius/knowledge/contacts/
  ✓ ~/.config/pontius/knowledge/templates/
  ✓ ~/.config/pontius/knowledge/rules/
  ✓ ~/.config/pontius/knowledge/policies/
  ✓ ~/.config/pontius/knowledge/patterns/
  ✓ ~/.config/pontius/knowledge/history/
  ✓ ~/.config/pontius/knowledge/invoices/
  ✓ ~/.config/pontius/knowledge/campaigns/
Knowledge base ready!

Check the status of your knowledge base:

$ pontius knowledge status
Knowledge Base Status
---------------------
Structure: folder (current)
Location: ~/.config/pontius/knowledge/
Content:
  contacts/     12 entries
  templates/    8 entries
  rules/        2 entries
  policies/     3 entries
  patterns/     5 entries

Migrating from Flat Files?

If you have an older Pontius setup with flat JSON files, run pontius knowledge migrateto convert to the folder structure automatically.

Why It Matters

Without a knowledge base, your AI assistant starts from zero every session:

Doesn't know who your VIP clients are
Doesn't know your preferred tone
Can't reuse responses that worked well
Treats every email as a new puzzle

With a knowledge base, the AI gets smarter over time:

Recognizes returning contacts and their preferences
Uses proven templates for common situations
Follows your account-specific rules
Automates routine tasks based on patterns

Components

Contacts

Store information about people you email:

{
  "email": "[email protected]",
  "name": "Sarah Chen",
  "company": "Big Client Inc",
  "relationship": "client",
  "tone": "professional, formal",
  "tags": ["vip", "enterprise"],
  "notes": "Always CC her assistant on important emails"
}

Learn more about contacts →

Templates

Reusable email responses with placeholders:

{
  "name": "Pricing Inquiry",
  "category": "sales",
  "body": "Hi {name},\n\nThanks for your interest! You can find pricing at {url}.\n\nBest,\nStuart",
  "tone": "professional"
}

Learn more about templates →

Rules

Per-account behaviors and defaults:

{
  "account_label": "Work",
  "default_tone": "professional but warm",
  "signature": "Best,\nStuart",
  "delegate_to": {
    "technical": "[email protected]"
  }
}

Learn more about rules →

Patterns

Automated actions triggered by email content:

{
  "name": "Billing Receipts",
  "match_sender": "(stripe|paypal)@",
  "suggested_action": "move:billing",
  "auto_apply": true
}

Learn more about patterns →

Policies

Business guardrails that prevent unwanted actions:

{
  "id": "no-refunds-without-approval",
  "name": "No Refunds Without Approval",
  "rule": "Never process refunds or offer money back without explicit approval",
  "applies_to": ["all"],
  "severity": "critical"
}

Policies define what the AI should never do, regardless of context.

Building Your Knowledge Base

The knowledge base grows organically as you use Pontius:

Start empty: Don't try to pre-populate everything
Add as you go: When you handle an email, note what worked
Review after sessions: Ask the AI to summarize what should be saved
Refine over time: Update entries as your understanding improves

Start Simple

You don't need a complete knowledge base to start using Pontius. Begin withPhase 1 (Stabilizers On) and build as you go.

How AI Uses It

The AI checks knowledge folders in priority order before handling emails:

Workflow for each email:
1. blitz/preferences.json → Load session preferences (tone, sign-off)
2. contacts/contacts.json → Do we know this sender?
3. patterns/patterns.json → Does this match a known email type?
4. rules/accounts.json → What are the account defaults?
5. templates/*.json → Do we have a response template?
6. policies/policies.json → Any guardrails for this action?

Priority order: policies (override everything) → contact preferences → account rules → blitz defaults → patterns/templates (suggestions)

Backup & Sync

Your knowledge base is included in pontius sync export. When you move to a new device, your entire knowledge base comes with you.

# Export everything including knowledge base
$ pontius sync export ~/backup.sync
# Import on new device (merge with existing data)
$ pontius sync import ~/backup.sync --merge
# Or replace everything
$ pontius sync import ~/backup.sync --force

The --merge flag intelligently combines imported data with your existing knowledge base, preserving local changes while adding new entries.

Next Steps

Blitz Preferences — Configure session settings
Contacts — Document your important contacts
Templates — Create reusable responses
Rules — Set up account behaviors
Policies — Define business guardrails
Patterns — Automate routine actions
History — Interaction log for learning
Invoice Presets — Company presets for invoicing
Campaigns — Outbound email sequences