> ## Documentation Index
> Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Personal agents that learn
> Give every user their own agent that remembers them and improves: one shared definition, per-user memory, and scheduled curation.
The product: a learning app where each user has an agent that knows *them*. It remembers their goals, adapts to their level, and gets better with every session. The design that scales is **one shared agent definition plus one memory store per user**, not one agent definition per user. The agent's *behavior* is versioned once and improved for everyone; what makes it personal is the memory it wakes up with.
## The architecture in one table
| Per-user thing | Checkfu resource |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Identity | One Principal (`external_subject_id` = your user ID) |
| What the agent knows about them | One **principal-owned** [MemoryStore](/concepts/memory) |
| A tutoring conversation | A Session mounting that store `read_write` |
| Getting smarter over time | The agent writes memory during sessions; [Dreams](/concepts/memory#curated-memory-dreams) distill it on a schedule |
| Spend safety | One [Budget](/guides/attribute-usage#cap-spend-per-user) per Principal |
The definition itself (instructions, harness, model, tools, shared skills) stays singular and published. You improve teaching quality for all users with one publish; no per-user version sprawl, and [sessions freeze their version at admission](/concepts/sessions-and-runs#two-freeze-horizons) so a mid-lesson upgrade can never happen.
`CHECKFU_API_KEY` and `CHECKFU_WORKSPACE_ID` come from [Get access](/reference/access#the-three-variables-ready). The TypeScript tab below uses the [TypeScript SDK](/reference/typescript-sdk) with this client:
```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Checkfu } from "@checkfu/sdk"
const checkfu = new Checkfu({
apiKey: process.env.CHECKFU_API_KEY,
})
```
On a user's first lesson, create their Principal, then their store:
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -s --request POST https://api.checkfu.com/v1/memory-stores \
--header "Authorization: Bearer $CHECKFU_API_KEY" \
--header "Checkfu-Version: 2026-08-27" \
--header "Idempotency-Key: store-user-4821" \
--header "Content-Type: application/json" \
--data '{
"name": "learner-4821",
"owner": { "kind": "principal", "principal": "prin_…" }
}'
```
```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const store = await checkfu.memory.create(
{
name: "learner-4821",
owner: { kind: "principal", principal: "prin_…" },
},
{ idempotencyKey: "store-user-4821" },
)
```
A principal-owned store mints its owner one `read` and one `write` PermissionAssignment at creation, and it is **not** proposal-gated. Only shared stores (environment-, agent-definition-, or surface-scope-owned) require [proposals](/concepts/memory#proposals). A personal store advances directly: it is the fast path by design.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"agent": "agent_tutor…",
"principal": "prin_…",
"mounts": [
{ "store": "memstore_learner_4821…", "access": "read_write",
"instructions": "This is your long-term memory about this learner. Read it before teaching; update it when you learn something durable about their level, goals, or misconceptions." }
]
}
```
The mount's `instructions` are how the agent knows what the store *is for*; that line is your pedagogy. The agent reads the store as an on-disk tree at `/mnt/memory/{store}` and writes to it as files. At turn settlement, a `read_write` personal store's changed files seal directly into its durable documents, with no proposal needed ([writeback at settlement](/concepts/memory#writeback-at-settlement)). Each seal records `memory.change_checkpointed` with content-addressed `base`/`new` tree digests, so you can tell what changed between one lesson and the next, and [erase](/concepts/memory#erasure) anything a user asks you to forget. (On a sandbox transport that cannot enumerate directories the agent still reads its memory as files but produces no writeback and fails closed.)
Raw memory accretes; teaching quality comes from distillation. Point a schedule-triggered [Automation with a `dream` target](/concepts/automations) at each user's store: every night it curates only the sessions it has not seen (`since_last`), merging duplicates and consolidating observations. Curation is deterministic, or model-curated with your `instructions` when you want editorial judgment.
This scheduled Dream loop is `preview` / `rollout_fenced` in [capability status](/getting-started/status). Dreams depend on the versioned Memory rollout; local development uses the qualified durable Postgres adapter, and the in-memory adapter is only its test and conformance oracle. Hosted enablement still waits on an operator-approved rollout of `MEMORY_VERSIONED_SURFACE`. Durable personal-document writeback has an independent support posture.
A Dream's output is a **new** Workspace-owned store: curation is copy-on-write, inputs untouched. Your app decides when the curated store becomes the one new sessions mount (and grants the user's Principal access to it). That swap is deliberate, so you can review a curation before adopting it, but it is yours to choreograph.
Three different things hide in "the agent learns". Keep them separate:
* **Per-user adaptation** belongs in memory. "Prefers examples over theory" and "struggles with recursion" are memory documents. This is the loop above, and it needs no shared-behavior review gate.
* **Better shared behavior** belongs in the Agent's instructions. On the Agent page, use **Improvements** to turn graded Outcome evidence into verdict-cited deltas, prove them with a baseline/candidate holdout, apply the winner to the draft, and publish only after human review. [Instruction improvements](/concepts/agents#improving-instructions-from-outcomes) cannot change a live Session or publish automatically.
* **New reusable capabilities** belong in [Skills](/concepts/capabilities). The [skill-source loop](/concepts/capabilities) proposes a skill edit as a pull request through a governed Connection; a human merges, sync pulls, and the next published Agent version delivers it.
This separation keeps personal facts private to one learner, makes global behavior changes measurable, and reserves code review for capability changes that deserve it.
* A per-Principal [Budget](/guides/attribute-usage#cap-spend-per-user) makes each learner's cost bounded and billable.
* On the rollout-fenced versioned surface, Memory search is deterministic and lexical. Recall is inspectable rather than an opaque embedding index, and what the agent retrieved appears in `memory.accessed` events.
* The whole settled learning model is auditable: sessions ([exportable](/guides/export-your-log)), memory revisions (diffable), curations (Dream records). Versioned history and curation remain behind the D7 rollout fence today. "Why does my kid's tutor think this?" has a readable answer once that surface is enabled.
## Next steps
Stores, revisions, working refs, and the proposal model this guide leans on.
Per-learner metering and caps.