Learned Knowledge

Reusable insights the agent accumulates — recalled by meaning, shareable across a team.

Learned Knowledge

In plain terms

Learnings are reusable insights that apply across many conversations — “Vendor X invoices always have line-item drift,” “customs holds explain 80% of ‘lost’ international shipments.” They’re recalled by meaning (semantic search), so the right insight surfaces even when the wording differs.

The analogy: the team wiki of hard-won lessons. One person figures something out once; everyone benefits forever.

Unlike User Facts (about a person) or Entities (about things), learnings are about how to do the work well.

When to use it

• Domain knowledge that accrues over time — support playbooks, troubleshooting patterns, gotchas.
• Team-shared know-how — promote an insight to agent or tenant scope so the whole team sees it (see Scope Hierarchy).
• Anything you want recalled by similarity, not exact match.

import { InMemoryVectorStore, OpenAIEmbedding } from "@agentium/core";

memory: {
  storage,
  learnings: {
    vectorStore: new InMemoryVectorStore(new OpenAIEmbedding()),
    topK: 3,
  },
}

When NOT to use it

• Facts about the user → User Facts.
• Exact-match lookups (an order by ID) → that’s a tool call, not memory.
• Static reference docs → use a Knowledge Base / RAG for large document corpora; Learnings is for short, agent-discovered insights.

Configuration

Property	Type	Required	Default	What it controls
vectorStore	VectorStore	Yes	—	Where learnings are indexed for semantic search
collection	string	No	"agentium_learnings"	The named bucket inside the vector store
topK	number	No	3	How many of the most relevant learnings to inject per run
minScore	number	No	none	Relevance floor (0–1) — matches below this similarity are never injected. Recommended 0.3–0.5; weak matches in context are a hallucination generator

Understanding the options:

• vectorStore is required because learnings are recalled by meaning, which needs a vector index (Qdrant, Pinecone, in-memory, etc.). This is why learnings takes an object, not just true — there’s no default backend.
• collection — change only if multiple agents should keep separate learning sets inside one vector database.
• topK — higher means the agent considers more accumulated knowledge but spends more tokens and risks losing focus. 3 is a solid default; 5–8 for knowledge-heavy agents, 1–2 for tight budgets.

Scope and sharing

Learnings support a four-level scope so insights aren’t trapped in one user’s silo:

global   ← built-in defaults, everyone
tenant   ← organization-wide (requires memory.tenantId)
agent    ← shared across all users of this agent
user     ← personal (default)

The save_learning tool exposes a scope parameter; reads union every scope the caller belongs to. Auto-extracted learnings always save as user scope — the framework never auto-promotes to a shared scope. See Multi-User Isolation for the full contract.

// Share an insight with the whole team using this agent
save_learning({
  title: "Vendor X line-item drift",
  content: "Vendor X invoices consistently show $0.10–$0.50 drift per line.",
  context: "invoice reconciliation",
  scope: "agent",
})

Provenance & trust tiers (v2.5+)

Every learning carries a source so the agent knows how much to trust it:

Source	Trust	Set by
"human-correction"	verified	Learnings derived from explicit human corrections
"manual"	verified	memory.remember() and programmatic saveLearning() calls
"llm-extracted"	unverified	Auto-extraction and the save_learning tool

Context injection annotates each line — [verified] / [unverified] — and appends a caveat whenever unverified items are present: “Items marked [unverified] are AI-extracted hypotheses — treat them as hints to verify, not established facts.” This stops the model from asserting AI-extracted guesses as truth.

Grounded extraction (v2.5+)

Auto-extraction is the main path for hallucinations to become permanent “knowledge.” Every extracted learning must now include an evidence field containing a verbatim quote from the conversation; extractions whose evidence doesn’t appear in the conversation text are rejected before they’re saved. The quote is stored on the record for audit.

Invalidation & self-correction (v2.5+)

Learnings can be retired without losing the audit trail:

// Manually retire a learning — removed from the vector index, kept in KV
await learnings.invalidateLearning(id, supersededByCorrectionId);

// Auto-retire unverified learnings that collide with new authoritative knowledge
await learnings.invalidateContradicted("Vendor X charge codes", {
  supersededBy: correctionId,
  threshold: 0.85,           // similarity floor
  agentName: "ap-reconciler",
});

invalidateContradicted only ever retires llm-extracted learnings — human-authored knowledge is never auto-invalidated. Recording a correction triggers this automatically. Invalidations emit memory.learning.invalidated events.

Pruning (v2.6+)

As volume grows, stale unverified learnings dilute retrieval. Prune them on a schedule:

const pruned = await learnings.pruneLearnings({
  maxAgeDays: 90,
  agentName: "ap-reconciler",   // owner filter (or userId)
  // sources: ["llm-extracted"]  — default: only unverified learnings are age-pruned
  // includeUntagged: false      — pre-v2.5 records without a source are kept
  // purgeInvalidated: true      — invalidated learnings past the cutoff are purged
});

Conservative by default: human-authored knowledge (manual, human-correction) is never age-pruned unless explicitly listed in sources. Curator.prune({ maxAgeDays, agentName }) now sweeps learnings alongside facts and decisions — see Curator.

Tools

Tool	What it does
save_learning	Save an insight (with optional scope)
search_learnings	Semantic search across every scope the caller can see

Cross-references

• Knowledge Base / RAG — for retrieving over large document sets
• Multi-User Isolation — the scope hierarchy in full
• Procedural Memory — reusable workflows (vs. reusable insights)
• Composite Scoring — how recalled learnings are ranked