{"id":"033b1ef5-edf9-4a62-9dcf-a8f22bd90483","slug":"feynman-loop","kind":"mcp","name":"Feynman-Loop","summary":"Explain-it-back as an MCP connector: it grounds a check in your own sources, scores it with verified evidence (not model vibes), and resurfaces what you don't yet know. Local-first, opt-in, no telemet","owner":"parvpatodia","repoUrl":"https://github.com/parvpatodia/Feynman-Loop","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-06-09T02:07:44.000Z","addedAt":"2026-10-21T06:13:02.122Z","logoUrl":"https://avatars.githubusercontent.com/u/233390324?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","developer-tools"],"tags":["active-recall","claude","claude-code","feynman-technique","learning-tools","llm","local-first","python"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T02:38:03.926Z","sample":false,"url":"https://conduits.dev/tools/feynman-loop","language":"Python","transports":["stdio"],"install":{"pypi":"feynman-loop"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Feynman-Loop\n\nA local-first tool that makes you understand what you learn (and what AI writes for you)\ninstead of offloading it. You explain a concept in your own words; it finds the gap against\nyour own source material, asks about the gap instead of answering it, and resurfaces the\nconcept later so the understanding sticks.\n\nIt runs as an MCP connector inside the AI tools you already use (Claude Desktop, Claude Code,\nCursor, ChatGPT Desktop, Gemini), with an optional web UI and CLI.\n\n## Honest summary first\n\nThis tool adds friction on purpose. Its whole premise is that struggling to retrieve and\nexplain something is what makes it stick, and that AI used too early removes that struggle.\nThat makes it useful for a specific person and a waste of time for everyone else. Read the\n\"Who this is for\" and \"Limitations\" sections before you install. They are not marketing\nhedges; they are the truth about where this helps and where it does not.\n\n## What it is\n\n- **Explain-it-back, grounded in your own material.** The scoring rubric is built from the\n  source you provide (a paper, your notes, a file of code), not from generic model knowledge.\n- **Gaps come back as questions, never answers.** The point is that you retrieve it.\n- **A transfer challenge** tests whether you can apply the idea to a case you were not shown,\n  not just restate it.\n- **A persistent competence ledger.** It records what you can and cannot explain, over time,\n  with due dates. This is the part a stateless chat cannot be.\n- **Verified scoring.** Every credited point must carry a verbatim quote from your own words\n  that the code checks; scores are computed in code, not asserted by a model. A judge cannot\n  grant credit it cannot point to.\n\n## What it is not\n\n- Not a summarizer (that offloads the thinking).\n- Not a flashcard app (that is retention without understanding).\n- Not gamified. One streak number tracks consistency. No points, no leaderboards.\n- Not \"AI that does the work for you.\" It is the opposite of that.\n\n## Who this is for\n\n- Students, bootcampers, career-switchers, and engineers onboarding into a new stack, where\n  mastering well-documented, canonical material is genuinely the job.\n- People prepping for a moment where they will have to explain their work out loud: an\n  interview, a code review, an exam.\n- Anyone who ships AI-written code and does not want to be unable to explain it later.\n\n## Who this is not for (be honest with yourself)\n\n- People who want AI to make their work faster and lighter. This makes it slower on purpose.\n- Frontier researchers working at the edge of a field. The judge grounds rubrics in a source;\n  if the truth of your work lives only in your head and not in any document, it cannot ground\n  anything useful. The tool is strongest on canonical material and weakest exactly where deep\n  novel expertise lives.\n\n## Limitations (read before installing)\n\n- **It fights a real habit.** Most people, most of the time, want less friction, not more.\n  If you will not actually do the reps, this tool will not change that.\n- **The \"teeth\" are opt-in and Claude Code only.** The commit-mode gate (below) that asks you\n  to explain shipped code before wrapping up is a Claude Code Stop hook. In Claude Desktop,\n  ChatGPT, Cursor, and Gemini there are no such hooks, so there it is pull-only: it helps when\n  you invoke it, and stays quiet otherwise.\n- **The line-count trigger is a rough proxy.** The shipped-code nudge counts AI-written lines,\n  including tests and docs, so it can fire on a large non-code change.\n- **Single user, single machine.** No accounts, no sync, no team features. The web UI is\n  unauthenticated and bound to localhost.\n\n## How it works\n\nTwo speeds:\n\n- **Rapid (default, 2-3 minutes):** say *\"quiz me on backprop\"*. One sharp question per rubric\n  point, a one-line answer from memory each, an instant verdict, a running score.\n- **Full:** you explain the whole concept in your own words and it is judged in one pass.\n\nEither way the rubric is grounded in your source, gaps return as questions, a transfer\nchallenge probes application, and the ledger schedules the concept to come back when due.\n\n## Controlling it: mode and scope\n\nProactivity is opt-in by design and you choose both how much and where.\n\n```\nfeynman-loop mode nudge     # default: offer an explain-back at a natural moment, never forced\nfeynman-loop mode commit    # self-armed gate: at session end, if you shipped unexplained\n                            #   AI-written code, you are asked to explain it before wrapping up.\n                            #   You can still decline; it fires once and never traps you.\nfeynman-loop mode off       # silence all proactive surfaces (explicit `feynman-loop due` still works)\n\nfeynman-loop scope          # show which projects the proactive hooks fire in (default: all)\nfeynman-loop scope add .    # only fire in this project (and any others you add)\nfeynman-loop scope remove . # stop firing here\nfeynman-loop scope all      # reset to firing everywhere\n```\n\nScope governs the always-on hooks; the MCP tools stay callable in any host where you have\nconfigured the connector. Scope is a convenience, not a security sandbox.\n\n### Project-scoped recall\n\nSpaced recall is scoped to the project you are working in. A concept is filed under the project\n(the git repo root) where you first explained it, and a session's due nudge surfaces only that\nproject's concepts plus a global bucket, so unrelated concepts do not interrupt the wrong project.\nConcepts that are not filed under a project are global and surface everywhere.\n\n```\nfeynman-loop projects                        # audit: every concept grouped by project (+ global)\nfeynman-loop reproject \"Backprop\" .          # file a concept under this project (default: cwd)\nfeynman-loop reproject \"Backprop\" --global   # send it back to the global bucket\n```\n\nA concept gets its project when the host passes the working directory to the check; the\nSessionStart hook prompts the host to do this. Concepts you captured before this, or in a session\nwhere the directory was not passed, stay global until you `reproject` them. Re-explaining a concept\nin another project never moves it on its own; `reproject` is the explicit, reversible way to move\nit (run it again, or with `--global`, to undo).\n\n## Setup\n\n**Terminal (recommended; Claude Code, Cursor, any MCP host, and the proactive hooks):** use an\nisolated virtualenv. Do not install into a global or conda environment; the optional vector\nstack (numpy, torch) is sensitive to ABI drift.\n\n```\npython3 -m venv .venv\n.venv/bin/python -m pip install -U pip\n.venv/bin/python -m pip install -e .                    # core: MCP server, pasted-source grounding\n.venv/bin/python -m pip install -e \".[embeddings]\"      # adds long-document grounding + web UI\n.venv/bin/feynman-loop init        # configures the MCP server + Claude Code hooks in one step\n```\n\n`init` also prints the config snippet for any other MCP host (ChatGPT Desktop, Gemini, Cursor).\nNormal pasted sources are grounded directly (the rubric sees the whole text, instantly); the\n`embeddings` extra is only needed for long documents and the web/CLI surfaces.\n\n**One-click bundle (Claude Desktop, no terminal):** build it on your own machine with\n`./scripts/build_mcpb.sh`, then double-click `dist/feynman-loop.mcpb` (or Claude Desktop >\nSettings > Extensions > Install Extension). The API key field is optional; leave it empty for\nzero-key mode. Needs Python 3.10+ and Node (for the bundler). The bundle ships native wheels, so\nit is platform-specific: build it on the OS you will run it on. A prebuilt bundle is not yet\nattached to Releases.\n\n## No API key? It still works\n\nYou do not need an API key inside an MCP host. With no `ANTHROPIC_API_KEY` set, the server runs\nin **zero-key mode**: the chat model you already pay for does the language work under a strict\nprotocol, and the server does the integrity work in code:\n\n- every credited verdict must carry a verbatim quote from your explanation, and the server\n  verifies the quote actually appears there; credit it cannot find is downgraded\n- rubric quotes are verified against your source passages the same way\n- every score is computed in code from the verified statuses, never taken from the model\n- minimum rubric sizes per depth are enforced, so a lazy one-point rubric is rejected\n\nWith a key, an independent judge model builds and scores instead, which is the strongest setup\n(your own chat model cannot be talked into leniency). The ledger records which judge scored\nevery event, so your history stays honest about its own strength. The terminal and web surfaces\ncall the API directly, so those two do need a key.\n\n## Data, privacy, and security\n\n- **Where your data lives:** one local SQLite ledger (owner-only, `chmod 0600`) plus a markdown\n  knowledge-graph vault, under `$FEYNMAN_HOME` (default `~/.feynman-loop`). It stores your\n  concept labels, a snapshot of the source material you give it, your verbatim explanations,\n  scores, and due dates. It never leaves your machine on its own.\n- **Where your data goes:** only judging calls leave the machine. With a key, your source\n  passages and explanations go to the Anthropic API under your key. In zero-key mode, the host\n  chat model you already use does the judging, so nothing leaves beyond what that host already\n  sees. Embeddings run locally. The web UI is localhost. There is no telemetry and no analytics.\n- **Secrets:** no API key is stored in this repo or its git history. Your key lives only in your\n  host's local config (for example Claude Desktop's config file), which is standard for every\n  MCP server. Zero-key mode needs no key at all.\n- **What the hooks record:** the shipped-code capture stores file names and line counts only,\n  never your code content. Out-of-scope projects are not recorded at all.\n- **Known sharp edges:** the web UI is unauthenticated and localhost-only, so anyone with local\n  access to your machine could use it and your key; treat it as a personal-machine tool. File\n  uploads to the web UI are not size-capped. Both are low risk for single-user local use, and\n  are why the web UI is optional and off by default.\n\n## Test\n\n```\n.venv/bin/python -m pytest -q\n```\n\n## Run the demo (CLI)\n\nNeeds the `embeddings` extra and an API key set in the shell only. Never commit the key or\npaste it anywhere shared. Prefer `feynman-loop check`, which tells you what is missing instead\nof a traceback.\n\n```\nexport ANTHROPIC_API_KEY=...\n.venv/bin/python -m feynman_loop.cli path/to/source.txt \"Backpropagation\"\n```\n\nYou type your explanation, then an empty line to submit. It returns the grounded gaps and, if\nyour explanation is solid, a transfer challenge. Sources can be `.txt` or text-based `.pdf`\n(scanned or image-only PDFs are not OCR'd).\n\n## Run the web UI\n\nNeeds the `embeddings` extra and an API key.\n\n```\nexport ANTHROPIC_API_KEY=...\n.venv/bin/feynman-loop web --port 8000\n```\n\nOpen http://localhost:8000, paste your source or upload a `.pdf`/`.txt`, name the concept, and\nexplain it. The grounded gaps and the transfer challenge render in the browser.\n\n## How the project is governed\n\nThree docs, read in order: `Principles.md` (the constitution), `Context.md` (current state and\nthe full decision log), `Learnings.md` (guardrails and findings). Contributions are welcome;\nthe design boundaries in `Principles.md` are deliberate and non-negotiable (no gamification,\nno forced interruption, grounding is mandatory).\n\n## License\n\nSee `LICENSE`.\n"}