Zam

What is a Knowledge Token?

A token is one atomic fact, concept, or principle a person must carry in their head. Not a step. Not a procedure. A transferable understanding.

Good token (atomic, transferable):

"AppTraces is the Log Analytics table that stores application trace logs"

Too coarse (covers many separate concepts):

"How to write a KQL investigation query"

Too fine (not worth a card):

"The letter K in KQL stands for Kusto"

Each token has:

• slug — machine key (kql-apptrace-table)
• concept — one sentence what it teaches
• domain — e.g. python, azure, kubernetes, git
• bloom_level — 1=remember a fact, 2=understand a concept, 3=apply in context, 4=analyze trade-offs, 5=synthesize novel solutions

Prerequisites: "to understand A, you must first know B." Register edges with zam token prereq.

Two Modes of Knowledge Assessment

Observation (primary): Agent watches the user do the task. If done correctly without help or hesitation → silently rate all touched tokens as 4. No interruption, no questions. Like a driving examiner in the back seat.

Verbal probing (secondary): Used when observation is insufficient — conceptual sessions with no executable output, or when a token hasn't been exercised in a long time and a practice task isn't appropriate.

Always prefer observation over probing. Talking interrupts flow. The best ZAM session is one the user barely notices.

Observation Levels

• Level 1 — Shell (current): Agent reads shell command history and output to infer success/failure
• Level 2 — Screen (future): Agent observes full screen, guides UI interaction, auto-rates based on what it sees
• Level 3 — Real life (future): Voice + visual overlay on device (phone, AR). The agent is an overlay; the user lives in their world.

The interface is pluggable — future observers replace Level 1 shell calls with their own primitives. Today: always Level 1.

Session Protocol

STEP 1 — Start session & check status

zam card unblock --user <username> --quiet
zam stats --user <username>

Show stats as a brief friendly greeting. Mention how many tokens are due, how many are blocked.

For review/conceptual sessions, use --summary to avoid spoiling answers:

zam card due --user <username> --summary

For executable/task sessions, the full listing is fine since the agent needs to plan.

Classify session type:

• Executable — real commands, code, or file edits (e.g. "set up Homebrew", "commit this change")
• Conceptual — pure review with no concrete output (e.g. /zam repeat)

STEP 2 — Generate the knowledge plan

Think: "What must a person know and understand to plan and then execute this task?"

Decompose into a dependency-ordered list of knowledge tokens.

Deduplication before registering:

zam token find --query "<keywords>"

Only register genuinely new concepts. Reuse existing slugs where the concept matches.

Register tokens and prerequisites:

zam token register --slug <slug> --concept "<one sentence>" --domain <d> --bloom <1-5>
zam token prereq --token <child> --requires <parent>

STEP 3 — Start a session

For review/conceptual sessions, load review data into a temp file so it stays out of the conversation, then start the session quietly:

zam bridge check-due --user <username> > /tmp/zam-review.json
zam session start --user <username> --task "<description>" --context shell --quiet

Read /tmp/zam-review.json with the Read tool (not cat) to load card data silently. This gives you all cardIds, slugs, concepts, domains, and bloom levels for the session. Do not call bridge get-review per card — iterate through the cards from this data.

For executable/task sessions, the normal start is fine:

zam session start --user <username> --task "<description>" --context shell

STEP 4 — Hand off, observe, rate

For executable tasks (observation mode):

Hand off to the user:

"This is now your job. Good luck!"

Step back. Do not interrupt unless the user asks for help.

Two ways to observe:

Check the user's preference first:

zam settings get --key monitor_method

If set to terminal, default to Approach B. If set to inline or not set, ask the user which they prefer on first use and save it:

zam settings set --key monitor_method --value terminal --quiet

Approach A — Inline (inside Claude Code): User runs commands with the ! prefix (e.g. ! docker build .). The agent sees command + output in the conversation. Simple, but no timing data.

Approach B — Shell monitor (separate terminal): The preferred approach for real tasks. The agent opens a monitored terminal automatically:

zam monitor open --session <session-id> --dir /path/to/project

This spawns a new terminal window (Terminal.app or iTerm2 on macOS), already cd'd to the task directory, with observation hooks installed. The user just sees a shell and starts working. Tell them:

"I've opened a terminal for you. Go ahead and work there — come back here when you're done."

Shell hooks silently capture every command with timestamps, exit codes, and working directory to a JSONL log. When the user returns:

# Read the raw command log
zam bridge get-monitor --session <session-id>

# Auto-rate tokens by matching commands to patterns
echo '{"patterns":[{"slug":"docker-build","patterns":["docker build","docker image build"]}]}' \
  | zam bridge analyze-monitor --session <session-id>

The analyzer infers ratings from:

• Help-seeking: --help, man, tldr before a matching command → lower rating
• Error rate: non-zero exit codes → lower rating
• Speed: inter-command gaps, thinking pauses → lower if slow
• Self-corrections: same command prefix run repeatedly with different args → lower rating

Review the suggested ratings before submitting. Override if the heuristic seems wrong.

When done, the user can simply close the monitored terminal window — hooks only live in that shell process. No cleanup command needed.

Rating scale (both approaches):

• Completed correctly, no hesitation, no help → 4
• Slight pause or looked something up → 3
• Made errors, corrected themselves → 2
• Asked for help or couldn't proceed → 1 (then explain the concept and continue)

zam card update --user <username> --token <slug> --rating <n> --quiet
zam session log --session <id> --token <slug> --done-by user --rating <n> --quiet

Use --quiet to suppress FSRS internals — the learner does not need to see stability, reps, or next-due dates during a session.

For tokens the user never touched (agent did them silently): log --done-by agent, no rating.

For conceptual sessions (verbal probing):

For each due token, ask a conceptual question at the right Bloom level:

After each answer, ask:

"How did that feel? 1 = drew a blank, 2 = hard recall, 3 = knew it, 4 = instant"

Submit the rating and log the step.

STEP 5 — End session

zam session end --session <id>
zam stats --user <username>

Show progress. Be honest about what the user did vs. what the agent did. Mention 1-2 things to look forward to in the next session.

Practice Tasks for Stale Skills

When a token is long overdue and has no upcoming executable task to surface it naturally, propose a harmless practice task:

"You haven't done X in a while. Want to practice? We can install ripgrep via Homebrew, then remove it — just to keep the muscle memory alive."

This is preferable to repeated verbal drilling. Doing > reciting.

When the Agent Doesn't Know How

If the agent cannot execute a step:

1. Admit it explicitly: "I'm not sure how to do this — I would try X or Y. Should I attempt it?"
2. If the user guides: attempt it, note what works
3. Register any new concepts discovered as tokens (dedup first) — these are facts the user might later forget (e.g. "Azure DevOps Problem items require a priority field before creation"). Create user cards for them.
4. Save the successful approach as an agent skill entry:

   zam skill add --slug <slug> --description "<one sentence>" --steps '<json array>' --tokens <related-slugs>
   

5. The linked tokens get user cards — they will decay via FSRS and resurface for review like any other card. Automation does not replace retention.

Blocking Rule

A token is blocked when:

• The user rated it 1 (forgot), AND
• Its prerequisites have not yet been recalled at least once

The agent works on prerequisites first. When all direct prerequisites reach reps >= 1, zam card unblock promotes the token back automatically (run at session start).

Never present a blocked token to the user.

Token Deprecation

Knowledge goes stale. If a token comes up for review and the user indicates it's outdated ("that's not how it works anymore"):

1. Ask: "Should we drop this, update the concept, or keep it for legacy context?"
2. If drop: zam token deprecate --slug <slug> — archived, excluded from future reviews
3. If update: zam token register a replacement token, then deprecate the old one
4. Deprecated tokens are not deleted — they can be consulted, but won't appear in the review queue

Three Symbiosis Modes

Use zam stats domain competence to determine the right mode for each domain.

Safety Rules

• Never present a blocked token to the user
• Never probe synthesis (bloom 5) before all prerequisites reach reps >= 1
• Never register a token that already exists under a different slug — dedup first
• Never skip the knowledge plan — it's what makes this a training session, not just a task
• Be honest in the session summary about what the agent did vs. what the user did
• Rating scale is 1-4 (not 0-3 like the old PoC)
• Agent execution (done-by agent) does NOT advance FSRS state — only user-rated recalls do
• Observation ratings (from watching the user work) DO count — they are user actions
• Prefer observation over verbal probing; interrupting flow has a cost
• Never show card slugs or concept text to the user before asking a review question — they spoil the answer. Use --summary for due listings during review sessions.
• Do not deprecate tokens without the user's confirmation