> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/memory/user-facts) (about a person) or [Entities](/memory/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](#scope-and-sharing)).
* **Anything you want recalled by similarity**, not exact match.

```typescript theme={null}
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](/memory/user-facts).
* **Exact-match lookups** (an order by ID) → that's a tool call, not memory.
* **Static reference docs** → use a [Knowledge Base / RAG](/knowledge/overview) 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](/memory/isolation) for the full contract.

```typescript theme={null}
// 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:

```typescript theme={null}
// 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](/memory/corrections) 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:

```typescript theme={null}
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](/memory/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](/knowledge/overview) — for retrieving over large document sets
* [Multi-User Isolation](/memory/isolation) — the scope hierarchy in full
* [Procedural Memory](/memory/procedures) — reusable *workflows* (vs. reusable *insights*)
* [Composite Scoring](/memory/scoring) — how recalled learnings are ranked