Learned Knowledge

In plain terms

Learnings are reusable insights that apply across many conversations — “Check Vendor X invoice totals against the itemized lines” or “Check customs status before escalating an international delivery.” 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; authorized readers can retrieve a relevant record later.

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 { Agent, type ModelProvider, type StorageDriver, type VectorStore } from "@agentium/core";

export function createLearningAgent(model: ModelProvider, storage: StorageDriver, vectorStore: VectorStore) {
  return new Agent({
    name: "learning-assistant", model, register: false,
    memory: { storage, learnings: { vectorStore, topK: 3, minScore: 0.4 } },
  });
}

This host factory receives configured dependencies. The host owns their credentials and scope; close the returned Agent after runs drain, retaining shared storage until host shutdown.

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

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Learned Knowledge

In plain terms

When to use it

When NOT to use it

Configuration

Provenance & trust tiers (v2.5+)

Grounded extraction (v2.5+)

Invalidation & self-correction (v2.5+)

Pruning (v2.6+)

Tools

Cross-references

​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

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