> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkfu.com/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 a plan for 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 plus one MemoryStore per user**, not one Agent per user. The agent's *behavior* is versioned once and improved for everyone; what makes it personal is the memory it wakes up with.
Plain HTTP against the Checkfu API needs no private package.
The Checkfu CLI and TypeScript SDK are optional private-alpha artifacts; the HTTP requests work without them.
Part of this flow is behind a rollout fence; a deployment that has not enabled it refuses the request rather than running it.
Confirm [capability status](/getting-started/status) before making availability part of your application's contract.
## 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; scheduled learning through ordinary [Automation](/concepts/automations) nodes remains planned |
| Spend safety | One [Budget](/guides/attribute-usage#enforce-a-principal-budget) 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#environment-variables-used-by-the-guides). 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-31" \
--header "Idempotency-Key: store-user-4821" \
--header "Content-Type: application/json" \
--data '{
"name": "learner-4821",
"owner": { "kind": "principal", "principal": "prin_0123456789abcdef0123456789abcdef" }
}'
```
```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const store = await checkfu.memory.create(
{
name: "learner-4821",
owner: { kind: "principal", principal: "prin_0123456789abcdef0123456789abcdef" },
},
{ 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 (Workspace-, agent-definition-, or collaboration-space-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_…",
"resources": [
{ "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 `base_version` and `new_version` MemoryVersion IDs, separate `tree_hash` and `diff_hash` content digests, and `changed_paths`, so you can inspect the retained changes, 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. The planned workflow composes ordinary [Automation](/concepts/automations) nodes: schedule → select authorized Session history → Agent analysis → validate → permitted Memory update or Skill proposal → record processed history. A learning template must expose an editable graph, selected resources and accounts, criteria, approvals and bounded revision.
Scheduled learning is not yet qualified end to end; see [capability status](/getting-started/status). It must use ordinary workflow identity and resource permissions, independently rechecking history reads and destination writes under personal/workspace ownership and revocation. Skill proposals change executable instructions and require the relevant validation and approval. Enabling versioned Memory does not enable this loop. Hosted rollout still requires operator approval; durable personal-document writeback has an independent support posture.
The workflow must name its actual destination and permitted action. Reading personal history does not authorize writing to a shared store or adopting a Skill proposal. Memory changes and Skill proposals need their own current resource permissions, validation and approval where required; processed-history tracking follows confirmed destination results.
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 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#enforce-a-principal-budget) 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)), MemoryVersions (diffable), curations (CurationRun records). Versioned history and curation remain behind the 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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.