Personal agents that learn

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 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
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 nodes remains planned
Spend safety	One 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 so a mid-lesson upgrade can never happen. CHECKFU_API_KEY and CHECKFU_WORKSPACE_ID come from Get access. The TypeScript tab below uses the TypeScript SDK with this client:

import { Checkfu } from "@checkfu/sdk"

const checkfu = new Checkfu({
  apiKey: process.env.CHECKFU_API_KEY,
})

Provision per user, lazily

On a user’s first lesson, create their Principal, then their store:

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" }
  }'

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. A personal store advances directly: it is the fast path by design.

Every lesson mounts the user's memory

{
  "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). 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 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.)

Learning between sessions: scheduled workflows

Raw memory accretes; teaching quality comes from distillation. The planned workflow composes ordinary Automation 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. 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.

Put each kind of learning in the right layer

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. The skill-source loop 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.

Safety rails that matter at per-user scale

A per-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), 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.

Get started

Agents

Sessions

Environments

Tools

Context

Automations

Permissions

Security

Billing

Deployment

Personal agents that learn

The architecture in one table

Provision per user, lazily

Every lesson mounts the user's memory

Learning between sessions: scheduled workflows

Put each kind of learning in the right layer

Safety rails that matter at per-user scale

Next steps

Memory

Attribute usage

​The architecture in one table

Provision per user, lazily

Every lesson mounts the user's memory

Learning between sessions: scheduled workflows

Put each kind of learning in the right layer

Safety rails that matter at per-user scale

​Next steps

Memory

Attribute usage

The architecture in one table

Next steps