Getting started

Install

No published package yet — install from source. The only runtime dependency is fg-agent-id (≥ 0.1.0); storage uses stdlib sqlite3.

git clone https://github.com/fareground-ai/agent-knowledge.git
cd agent-knowledge
pip install -e ".[dev]"

Requires Python ≥ 3.11. The package is fully typed (py.typed ships in the wheel).

Run the test suite (hermetic — no network, no LLM, no async):

python -m pytest

First knowledge base in five minutes

Two agents share a workspace: a scout proposes knowledge, an analyst reviews it.

from fg_agent_id import KeyPair
from fg_agent_knowledge import KnowledgeBase, Policy, Scope, SQLiteStore

# 1. Identities — every record is signed by its author
scout, analyst = KeyPair.generate(), KeyPair.generate()

# 2. A knowledge base: one SQLite file, one scope (a shared space)
kb = KnowledgeBase(SQLiteStore("team.db"))
scope = Scope(space="workspace-42")

# 3. Governance: claims need one approval from someone other than the proposer
kb.set_policy(scope, Policy(mode="review", required_approvals=1))

# 4. Capture an observation (cheap, unsigned, append-only)
ep = kb.observe(scope, scout, "observation", "deploy failed twice on cold cache")

# 5. Propose a claim distilled from it — the episode id is its pedigree
promo = kb.propose(
    scope, scout, "procedural",
    "warm the cache before deploying the pricing service",
    topics=("deploy", "pricing"), episodes=(ep.id,),
)

# 6. A different identity approves; the claim enters the scope
promo = kb.review(promo.id, analyst, "approve", basis="matches incident log")
assert promo.status == "accepted"

# 7. Ask for a briefing — ranked, attributed, model-free
briefing = kb.brief(scope, task="deploy pricing service")
top = briefing.items[0]
print(top.claim.body.statement, top.confidence, top.verify_first)

What just happened

• observe recorded raw experience. Episodes are fuel for later distillation — they are never returned by briefings directly.
• propose created a signed, content-addressed claim and opened a promotion under the scope's policy. In review mode it waits for approvals.
• review was performed by a different identity — the proposer can never approve their own promotion.
• brief assembled a ranked answer from accepted claims: relevance × confidence × freshness. verify_first flags items that are stale or suspect.

Where to go next

• Understand the trust model and governance rules → Concepts
• Full method-by-method reference → API
• Contradictions, invalidation, custom retrievers, trust weighting → Examples