English · 한국어
A university in your hand. become is a local-first personal learning system with one coordinator, five specialist-agent contracts, evidence-backed learning paths, and time-based memory review. The specialist model implements the responsibilities demonstrated in this ALTER learning workflow, while the data and enforcement layer remain deliberately small and local.
Orchestrator workflow order, dependencies, interruption and resumption
├─ Advisor destination, baseline, sequence, exclusions, proof milestones
├─ Librarian source triage and a focused shelf of 3–4 materials
├─ Tutor teaching, confusion diagnosis, connections, delayed retrieval
├─ Editor version-bound critique and learner revision loop
└─ Roommate questions through a deliberately different field
AGENTS.md is the single contract for every role, agents/librarian.md is a prompt copy for the one role that runs in a separate context, and
permissions, and become.py stores and validates their outputs. It uses only the Python standard library.
Real specialist contexts run in the current agent host (Claude Code, Codex CLI, and similar).
Open this repository in your agent host and just ask to learn something. Claude Code loads CLAUDE.md,
Codex CLI natively reads AGENTS.md, and Gemini CLI reads GEMINI.md; each session becomes the
Orchestrator. You can also inspect the first route locally:
python3 become.py --actor orchestrator orchestrator route --intent learn
python3 become.py --actor orchestrator orchestrator workflow-start --intent learn --request "learn backpressure for production systems"The workflow starts only the roles required by current state. A new learner normally follows
Advisor → Librarian → Tutor → Advisor; an existing ready shelf can start at Tutor. Editor and Roommate are
invoked when a deliverable or an outside-field perspective is actually useful.
One sentence about the learner's desired identity is enough for Advisor to choose five planning decisions without asking follow-up goal questions: destination, baseline, prerequisite order, a cut list, and milestones proven by learner work. When performance evidence is absent, Advisor records a conservative unverified baseline and uses the first Tutor application to calibrate it. Tutor observations update this path, and previously resolved confusion can return as a remedial objective when estimated retention decays. Every sequence step needs proof; only the active step can be completed, and its evidence must belong to the current curriculum version before the next prerequisite-ready step opens. Changing the study goal or core focus archives the old profile and curriculum and lets Advisor choose a fresh five-decision path. The old subject's knowledge stays in maintenance: it keeps its due retrievals and remedial goals but is excluded from new teaching and practical goals, and returning to that goal makes it the current learning target again.
Librarian opens the source and separates reachability from content verification. Every candidate receives a reasoned decision for relevance, credibility, level fit, signal density, and 1–5 priority, bound to a curriculum version and step. Only verified, triaged signal enters a shelf, with the strongest 3–4 sources selected for the active step. Byte-identical copies count once, and reachability plus the full content fingerprint are checked again before use. Empty, too-basic, and too-advanced sources cannot enter it. Tutor cannot cite stale, future-step, invalidated, changed, missing, or unselected material.
Tutor teaches new material before testing it, identifies the first point of confusion, and always explains why it
is used, why it took this form, why the result follows, and where it is applied. A connection must resolve to one
active related knowledge item in the current subject or one Advisor-committed curriculum baseline.
It stores the exact prompt, answer, rating rationale, confidence, weak points, and bidirectional concept links.
Same-titled concepts in different subjects keep separate memory state. Due retrievals are not forced up front:
tutor recall finds due knowledge overlapping the current topic so Tutor can weave it in as "remember this
from last time", and an explicit review session opens with --intent review. A new-learning step requires
post-claim teaching followed by a different-case application review; a due step requires an unaided retrieval
review followed by why/connection teaching that addresses the answer. The first application review, not the row
creation or teaching timestamp, starts the forgetting clock.
Editor stores purpose, audience, and the learner's version. It reviews thinking, logic, evidence, repetition,
structure, precision, and accuracy. Each finding identifies the affected span, diagnosis, and learner action.
The learner submits the next version; Editor re-reviews it, resolves repaired findings, and links a returning
problem as regressed. Open
findings or failed milestone criteria cannot receive a pass, and previous_versions remains available for audit.
Whitespace- or Unicode-only resubmissions are not new learner revisions.
Version-3 artifacts without author provenance are quarantined as legacy_unknown and cannot be reviewed or used
as milestone evidence until the learner explicitly resubmits them.
Roommate is not a session checkpoint. It introduces a concrete mechanism from a different field, asks one
connection question, waits for the learner's answer, and records the mapping and where the analogy breaks.
Connections may explicitly end as no_connection or needs_verification instead of being forced.
Only one unanswered perspective can exist at a time, and the same lens/question pair cannot be replayed.
When the learner has other stored subjects, route --intent perspective lists them as other_majors, the
preferred outside fields before any invented one.
Orchestrator owns workflow order and session continuity. A dependent step cannot be claimed early, and a workflow
step cannot complete with a summary or an unrelated old id: it needs the expected output created or changed
after that step began. Completed results are copied into the next step's context. This is why the
coordinator exists: it enforces accountability without pretending to plan, teach, research, edit, or invent a
perspective itself. Manual handoffs use the same role-completion checks and take their snapshot at claim time.
If a parallel request changes the bound curriculum version, the stale workflow/handoff becomes
superseded/cancelled. The plan performing a goal/focus change rebinds to the new target; other stale work is
cancelled. Retention changes also re-route in-flight learning modes. One semantic output version cannot complete
two requests. Tutor must return observations and recommendations; the following Advisor must record that exact
observation as level evidence and link its goal to that knowledge id. Evidence records both the source Tutor handoff
and producing Advisor handoff, so one Tutor observation cannot satisfy two Advisor updates. A session linked by workflow id
resumes with the live workflow, current step, and handoff.
Every specialist write requires a claimed handoff. Different roles may run in parallel, but each role can have only
one in-progress handoff. Changed resources are stamped with that producing handoff, preventing composite or replayed
outputs; --scope-handoff can bind a command to it explicitly.
A manual Advisor handoff declares curriculum or advisor_update; Editor's artifact id is bound at dispatch.
Roommate receives only the current field/problem, creates the outside field, lens, and question itself, and binds
that perspective to the claimed handoff so it cannot be swapped before completion.
Specialist write commands below run only after that role claims an Orchestrator handoff.
python3 become.py --actor advisor advisor decide --decision destination --choice "Defend a queue-capacity decision with load evidence" --rationale "Observable operational outcome" --evidence "Learner aspiration"
python3 become.py --actor advisor advisor curriculum --spec '{...}'
python3 become.py --actor advisor advisor recommend # read-only; never writes state
python3 become.py --actor advisor advisor next # write path; needs a claimed Advisor handoff
python3 become.py --actor librarian librarian add --title "official guide" --source "/path/to/source" --evidence "sections read directly"
python3 become.py --actor librarian librarian curate MATERIAL_ID --assessment '{...}'
python3 become.py --actor librarian librarian shelf --curriculum-id CURRICULUM_ID --step-id STEP_ID --candidate-id MATERIAL_1 --candidate-id MATERIAL_2 --candidate-id MATERIAL_3
python3 become.py --actor librarian librarian prefetch --source "/path/to/source" # read-only warm-up, no claim needed
python3 become.py --actor tutor tutor recall --topic "topic being taught" # related due knowledge to weave in
python3 become.py --actor tutor tutor teach KNOWLEDGE_ID --explanation "왜 쓰는가: ... 왜 이렇게 되었는가: ... 왜 이 결과가 나오는가: ... 그래서 어디에 쓰는가: ..." --connection "stored related knowledge or curriculum baseline"
python3 become.py --actor tutor tutor review KNOWLEDGE_ID good --confidence complete --prompt "question" --answer "learner answer" --rationale "rating basis"
python3 become.py --actor learner editor add --title "deliverable" --content "draft" --purpose "decision" --audience "team"
python3 become.py --actor editor editor review ARTIFACT_ID --criteria '{...}' --milestone-criteria '{...}' --verdict revise --next "learner action"
python3 become.py --actor learner editor revise ARTIFACT_ID --content "learner revision"
python3 become.py --actor roommate roommate ask --current-field "distributed systems" --problem "backpressure" --outside-field "urban traffic" --lens "ramp metering" --question "Where should admission be limited?"
python3 become.py --actor orchestrator orchestrator session-start --context "commute" --workflow-id WORKFLOW_ID
python3 become.py --actor orchestrator orchestrator session-resume
python3 become.py --actor orchestrator orchestrator dispatch --to advisor --task "update path" --output-kind advisor_update
python3 become.py --actor orchestrator orchestrator dispatch --to editor --task "review current draft" --resource-id ARTIFACT_ID
python3 become.py --actor orchestrator orchestrator workflow-start --intent perspective --request "outside lens" --current-field "distributed systems" --problem "backpressure"
python3 become.py --actor orchestrator orchestrator route --intent review # explicit review; opens only when something is dueUse python3 become.py --help and each role's --help for the complete command surface.
Personal state lives in .become/state.json; review audit events live in .become/reviews.jsonl. .become/ is
ignored by Git. Every CLI writer uses the same inter-process lock and compare-and-swap; a local transaction
journal restores the previous consistent pair if the process exits while both files are changing. Set BECOME_HOME
to use another private directory.
Version-3 state is migrated without inventing provenance; malformed nested role or orchestration state already marked v4 is
rejected instead of silently normalized.
estimated retention = 0.9 ^ (elapsed days / stability days)
An interaction before due_at is exposure and cannot increase stability. Only an independent answer after the
delay is retrieval. Partial or failed confidence requires a concrete weak point. Resolved confusion remains in
history so Advisor can schedule it again after likely forgetting.
python3 -m py_compile become.py
python3 -m unittest -vThe suite covers role success and invalid transitions, access denial, workflow dependencies, populated-state migration, source gating, memory timing, and a complete six-role journey.
become.py local execution and state engine
AGENTS.md Orchestrator contract
agents/ librarian prompt copy (the only role run in a separate context)
tests/ role, migration, and journey verification
.become/ Git-ignored personal data