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.

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

Decision Log Correction Capture

​Learned Knowledge

​In plain terms

​When to use it

​When NOT to use it

​Configuration

​Scope and sharing

​Provenance & trust tiers (v2.5+)

​Grounded extraction (v2.5+)

​Invalidation & self-correction (v2.5+)

​Pruning (v2.6+)

​Tools

​Cross-references