knowledge-base

name	knowledge-base
description	fact, decision, architecture, knowledge, permanent, remember forever, always know, decisions, outcomes, lessons learned

Knowledge Base - Permanent Facts and Decisions

Quick Start

Knowledge is PCP's permanent memory for facts that should never be forgotten:

• Facts: "API rate limit is 100 req/min"
• Architecture: "MatterStack uses Redis for caching"
• Preferences: "the user prefers concise responses"
• Decisions: Explicit choices with rationale and outcomes

Script: knowledge.py

Capture vs Knowledge - When To Use Each

Use Case	Tool	Example
Something the user says in conversation	smart_capture()	"John mentioned the API is slow"
Permanent fact to remember forever	add_knowledge()	"API rate limit is 100 req/min"
Explicit decision with rationale	record_decision()	"Decided to use Redis for caching"

Rule of thumb:

• Capture: Transient observations, conversations, notes
• Knowledge: Permanent facts, architecture, preferences
• Decision: Explicit choices that may need outcome tracking

Knowledge Functions

Add Knowledge

from knowledge import add_knowledge

# Basic usage
knowledge_id = add_knowledge("MatterStack uses Redis for session caching")

# Full options
knowledge_id = add_knowledge(
    content="API rate limit is 100 requests per minute",
    category="architecture",     # architecture|decision|fact|preference
    project_id=5,                # Link to project
    confidence=0.9,              # 0.0-1.0 confidence level
    source="John's email",       # Where this came from
    tags=["api", "limits"]       # Tags for organization
)

Query Knowledge

from knowledge import query_knowledge, list_knowledge, get_knowledge

# Search by content
results = query_knowledge("Redis")
results = query_knowledge("rate limit", category="architecture")

# List all or filtered
all_knowledge = list_knowledge()
facts = list_knowledge(category="fact")
project_knowledge = list_knowledge(project_id=5)

# Get by ID
knowledge = get_knowledge(42)

Update and Delete

from knowledge import update_knowledge, delete_knowledge

# Update (only provided fields change)
update_knowledge(42, content="Updated content", category="decision")

# Delete
delete_knowledge(42)

CLI Usage

# Add knowledge
python knowledge.py add "MatterStack uses Redis" --category architecture
python knowledge.py add "the user prefers concise responses" --category preference --source "Observation"
python knowledge.py add "API limit is 100/min" --category fact --project 1 --tags "api,limits"

# Search
python knowledge.py search "Redis"
python knowledge.py search "rate limit" --category architecture

# List
python knowledge.py list
python knowledge.py list --category fact
python knowledge.py list --project 1 --limit 10

# Get by ID
python knowledge.py get 42

Decision Tracking

Decisions are special - they have outcomes that should be tracked.

Record a Decision

from knowledge import record_decision

decision_id = record_decision(
    content="Use Redis for caching instead of Memcached",
    context="Redis supports more data structures, team has experience",
    project_id=5,
    alternatives=["Memcached", "No caching", "In-memory only"]
)

Link Outcome (Later)

When you learn how a decision turned out:

from knowledge import link_outcome

link_outcome(
    decision_id=42,
    outcome="Redis worked well, 50% latency reduction",
    assessment="positive",       # positive|negative|neutral
    lessons_learned="Should have configured eviction policy earlier"
)

Find Decisions Needing Follow-up

from knowledge import get_decisions_pending_outcome, list_decisions

# Get old decisions without outcomes (default: 30+ days old)
pending = get_decisions_pending_outcome(days_old=30)

# List decisions with filters
all_decisions = list_decisions()
project_decisions = list_decisions(project_id=5)
decisions_with_outcomes = list_decisions(with_outcome=True)
pending_decisions = list_decisions(with_outcome=False)

CLI for Decisions

# Record a decision
python knowledge.py decision "Use Redis for caching" --context "Team experience" --project 1
python knowledge.py decision "Hire contractor for UI" --alternatives "hire full-time,use agency"

# Link outcome
python knowledge.py outcome 42 "Redis reduced latency 50%" --assessment positive
python knowledge.py outcome 42 "Didn't work, too complex" --assessment negative --lessons "Start simpler"

# List decisions
python knowledge.py decisions
python knowledge.py decisions --pending           # Without outcomes
python knowledge.py decisions --with-outcome      # With outcomes
python knowledge.py decisions --project 1

Categories Explained

Category	Use For	Examples
fact	Objective truths	"API limit is 100/min", "John's email is [e-mail]"
architecture	Technical decisions	"Uses Redis", "Frontend is React"
decision	Explicit choices	"Decided to use X over Y"
preference	the user's preferences	"Prefers concise responses"

When User Says...

User Says...	Action
"Remember that X uses Y"	add_knowledge(content, category="architecture")
"It's a fact that..."	add_knowledge(content, category="fact")
"I prefer X"	add_knowledge(content, category="preference")
"We decided to..."	record_decision(content, context)
"That decision worked out because..."	link_outcome(id, outcome, assessment)
"What do we know about X?"	query_knowledge(query)
"What decisions have we made about X?"	list_decisions(project_id=X)
"What decisions need follow-up?"	get_decisions_pending_outcome()

Database Tables

Table	Purpose
knowledge	Permanent facts, preferences, architecture
decisions	Explicit decisions with outcome tracking

Knowledge Table Fields

• id, content, category (architecture/decision/fact/preference)
• project_id (optional link to project)
• confidence (0.0-1.0)
• source (where it came from)
• tags (JSON array)
• created_at, updated_at

Decisions Table Fields

• id, content, context (rationale)
• alternatives (JSON array of alternatives considered)
• project_id, capture_id (optional links)
• outcome, outcome_date, outcome_assessment (positive/negative/neutral)
• lessons_learned
• created_at

Related Skills

• /vault-operations - Transient captures and searches
• /brief-generation - Briefs include recently added knowledge
• /project-health - Project context includes related knowledge