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
A tutoring conversation	A Session mounting that store read_write
Getting smarter over time	The agent writes memory during sessions; Dreams distill it on a schedule
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,
})

1. Provision per user, lazily

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

   cURL

   curl -s --request POST https://api.checkfu.com/v1/memory-stores \
     --header "Authorization: Bearer $CHECKFU_API_KEY" \
     --header "Checkfu-Version: 2026-08-24" \
     --header "Idempotency-Key: store-user-4821" \
     --header "Content-Type: application/json" \
     --data '{
       "name": "learner-4821",
       "owner": { "kind": "principal", "principal": "prin_…" }
     }'
   

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

2. Every lesson mounts the user's memory

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

3. Learning between sessions: Dreams

   Raw memory accretes; teaching quality comes from distillation. Point a schedule-triggered Automation with a dream target 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. 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.

4. 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.

5. 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), 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

Memory

Stores, revisions, working refs, and the proposal model this guide leans on.

Attribute usage

Per-learner metering and caps.