GitLearnOS: A Protocol That Stores Your Learning State in Your Own Git Repo

Forum topic · QianXun · 2026-08-21

Summary

GitLearnOS is an open protocol (v2.0-draft) that addresses a core gap in AI tutoring: most AI tutors forget the learner when the session ends. Instead of trying to teach better, GitLearnOS gives a replaceable main AI agent a learner-owned Git repository as its durable memory. The repo is the single source of truth; RAG, schedulers, and a DeepSeek Harness host are optional, non-authoritative layers with strict scope boundaries. Learning events, knowledge gaps, reusable models, spaced reviews, and dashboard state are written as one atomic, reversible commit via learning_apply in safe-auto, preview, or manual mode. Diagnosis is disciplined: surface errors are signals, not verdicts; competing hypotheses must be differentiated by 1-3 targeted probes before a supported label is written, otherwise status stays unknown, suspected, or falsified. Mastery has only three levels and demands delayed, independent transfer evidence. Correctness is transparent: git revert, linked corrections, no silent rewrites, no claims without proof. The project ships 18 documented evaluation scenarios with machine-checkable JSON artifacts and a Developer Preview native package for DeepSeek Harness, with proven and unproven capabilities clearly separated.

Key points

Core promise. GitLearnOS is a platform-agnostic behavior contract (protocol 2.0-draft), not an app or a model. Learning can happen anywhere; the main agent only consumes useful evidence and never answers on the learner's behalf. State defaults to private, fully local Git, with remote repos only on explicit opt-in for backup, cross-device, teacher review, collaboration, or publishing.
Four-layer architecture with no layer overstepping. Git repo = authoritative, versioned truth (required). RAG (RAG-Anything, optional) = retrievable overlay only. Scheduler (optional) = wakes the same main agent for due reviews, never spawns a second learning agent. DeepSeek Harness host (Developer Preview) = pipeline for verified Git transactions and a read-only panel. None of these layers may become a second source of truth.
Atomic, reversible learning transactions. A real learning event is condensed into evidence, optionally a targeted question, the learner's response or external feedback, an updated next step, and a single git revert-able commit. In safe-auto, learning_apply writes event/knowledge-gap/model/review/dashboard atomically after four checks: learner identity, setup/config, base revision, write authorization. preview shows proposed diffs without writing; manual waits for confirmation. Every write returns a receipt with changed files and the exact git revert boundary. Deletions, long-term goal changes, publishing, secrets, and broad refactors always require explicit confirmation.
Differential diagnosis, not labeling. A wrong answer is a signal, not a diagnosis. The protocol requires enumerating competing hypotheses, then asking 1-3 discriminating questions to isolate the live one. Only when positive discriminative evidence exists and alternatives are weakened can a supported label be written; otherwise the status stays suspected or unknown. Mastery has only three levels: unknown (no valid evidence), learning (attempted or completed with help), and demonstrated (delayed, independent transfer). Reading, finishing, or freshly imitating does not count as mastery.
Three learners, one wrong answer, three paths. On y = −2x² + 4x + 1, Student A lacks the sign-to-opening link (drill the chain), Student B knows the concept but cannot recall the vertex formula (restore it or switch to completing the square), Student C simply missed a minus sign (confirm and avoid over-training).
Correctness, auditability, portability. Corrections are new linked records, never silent rewrites. git revert undoes the last learning update. Old judgments can be reopened when new evidence conflicts. The dashboard is a current snapshot, never a parallel source of truth. Learners can switch main agents (Claude Code, Codex, OpenCode, any Git-capable runtime) without losing state. Pure local Git works; GitHub is not required. Large PDFs/scans live in authorized local folders or Project Sources; the repo stores only compact state, provenance pointers, and seen excerpts.
DeepSeek Harness native package (Developer Preview). A no-build Host + browser client is discoverable via Harness profile and supports constrained learning_status / learning_route reads, one learning_apply transaction authorized by gitlearnos.yml, and a read-only panel with five queue actions (review, practice, MCQ wrap-up, ask teacher, view notes). Narrow host earns at most host-baseline-pass; full-pass requires a writable integration. RAG is not in scope. Vision depends on either a multimodal third-party model or an authorized vision/OCR bridge plugin; without one, the agent must ask the learner to transcribe image content rather than guess.
Canonical setup and readiness gates. A single canonical setup prompt forces the agent to read the full protocol, ask once about goals/subjects/materials/optional RAG, persist AGENTS.md and native memory, and test-run on two real schedulers. Minimum repo = gitlearnos.yml, AGENTS.md, automation.md, dashboard.md, learner-profile.md, subjects/<subject>/goals/main-goal.md. gitlearnos.yml ships honest defaults: mode: safe-auto, push: false, store_conversations: false, rag.choice: undecided (not ready until decided), plus two daily jobs (due-review 07:00, maintenance 21:30). Readiness is computed from verifiable evidence, not marketing copy: core-ready, knowledge-ready, automation-ready, full-ready, or honest incomplete.
Evaluation. Eighteen documented scenarios cover first-turn onboarding, note consolidation, reconciling teacher feedback, due-review generation, independent response write-back, anti-spoofing and dedup, GitHub-free operation, constrained SAT study, implicit event detection, GitHub teacher collaboration, continuity without skills, cross-agent install validation, optional RAG routing, distilling recurring errors into a transferable model, repeated organization and question generation, DeepSeek Harness native validation, diagnosis-before-writing, and not triggering interrogative diagnosis for new learning. Acceptance requires the repo and receipts to meet each invariant; a machine-checkable JSON artifact schema backs the suite.

Critical assessment

Strengths: vendor-neutral, learner-owned, portable state; evidence-linked, correctable, auditable history; rare rigor in differential diagnosis; explicit proven-vs-unproven discipline; machine-checkable evaluation.
Risks and open issues: Developer Preview maturity is unproven; single-maintainer bus-factor; not turnkey (requires a Git-capable AI runtime and setup friction); commit noise over time demands disciplined reconcile/dedup; large materials pressure the optional RAG layer; default text-only vision forces workarounds; the true success criterion (later independent performance) is hard to self-verify; public adoption is unknown, not zero.

Quick comparison

| Dimension | GitLearnOS | Generic LLM tutor | Khanmigo-style | Anki-style | |---|---|---|---|---| | State ownership | Learner's Git repo (private, portable) | Platform session (evaporates) | Vendor cloud (lock-in) | Local/account (cards only) | | Diagnostic depth | Competing hypotheses + discriminative probes + write threshold | Usually direct explanation | Medium, Socratic-leaning | None (pure spacing) | | Correctability | git revert + linked corrections | Largely invisible | Weak | Card editing | | Cross-agent portability | Yes (repo = state) | No | No | Partial (export) | | Needs a model | Yes (external runtime) | Yes | Yes | No | | Honesty discipline | Strong (proven vs unproven) | Variable | Vendor self-claim | N/A |

One-line takeaway: GitLearnOS does not sell "an AI that teaches you better"; it sells "a learning truth that no AI vendor can hold hostage."

Sources

GitHub repo (MIT License, v2 protocol in development): https://github.com/Guojiz/GitLearnOS
Official site: https://guojiz.github.io/gitlearnos/
README.md, zh-CN/GITLEARNOS.md (and machine-executable GITLEARNOS.md), zh-CN/QUICKSTART.md, docs/deepseek-harness-launch.md, evals/README.md
Chinese intro video: https://b23.tv/n2DTU1d