Knowledge base awareness

Knowledge Base Awareness

Purpose

Make the existence of a knowledge-base capability available to the agent without turning every task into a knowledge project.

Core rule:

Notice before creating. Establish future use before preserving.

A knowledge base is governed, reusable understanding about a bounded object. It is not synonymous with chat history, search history, a document folder, a database, or generic memory.

Trigger Signals

Assess the opportunity when one or more signals appear:

• the user repeatedly re-explains the same object, constraint, vocabulary, or decision;
• multiple Pi agents or profiles work on the same object;
• corrections must survive later sessions;
• current truth must be separated from historical statements;
• evidence changes, expires, conflicts, or becomes invalid;
• consequential decisions and their rationale must remain available;
• an agent is producing an understanding likely to affect future work;
• existing artifacts preserve data but not the judgment needed to use it.

Signals are prompts to assess, not permission to build.

Opportunity Assessment

Before recommending a knowledge base, answer:

1. Object: What bounded object or problem space would the knowledge describe?
2. Future use: Which future question, judgment, action, or handoff would it improve?
3. Users: Which agents or people would use it?
4. Continuity failure: What is currently forgotten, repeated, contradicted, or misapplied?
5. Existing authority: Is there already a source of truth that should be used rather than duplicated?
6. Change: How often does the relevant understanding change?
7. Consequences: What is the cost of forgetting it or treating it as true incorrectly?
8. Boundary: What must remain session-local, agent-local, private, or excluded?
9. Validator: Who can correct or authorize consequential shared knowledge?

Use templates/kb-opportunity-assessment.md relative to the package root when a durable assessment is warranted.

Outcomes

Choose one explicitly:

• No durable record: one-off or low-value work.
• Session context: useful only during the present task.
• Agent-local memory: useful to one agent but inappropriate for sharing.
• Existing source of truth: retrieve or improve an existing authority rather than creating another.
• Evidence preservation: retain an artifact without claiming it is knowledge.
• Candidate knowledge base: recurring, bounded, governable understanding has plausible future value.
• Clarification required: the object, future use, boundary, or authority is not understood.

Communication Pattern

When a candidate exists, say plainly:

A knowledge-base capability is available. I think it may help because [continuity failure].
The bounded object appears to be [object], and it would support [future decision/use].
I have not decided what belongs in it yet. The next step is object understanding and an admission review.

Do not imply that a database or interface must be built.

Handoff

If the outcome is candidate knowledge base, load knowledge-base-curation before defining schemas, seeding claims, importing history, or choosing a backend.

If proposals may become shared across agents, load knowledge-base-governance before promotion.

Anti-Patterns

• Creating a knowledge base because the feature exists.
• Treating all durable memory as shared knowledge.
• Beginning with tables, embeddings, graph nodes, or UI.
• Using one pilot object as the architecture for every object.
• Bulk-promoting transcripts, documents, or model summaries.
• Claiming that installation means the agent understands an object.

Completion Check

• The bounded object is named or explicitly unresolved.
• A real future use is named.
• Existing sources of truth were considered.
• privacy and sharing boundaries are provisional or known.
• An explicit outcome was selected.
• No storage was created merely from trigger signals.