A context engineering plugin for Claude Code. It teaches Claude how to work with what you know.

Episodic memory gives Claude recall. Learning-loop gives Claude judgment. It verifies sources before anything lands in your vault. It gates promotion on quality scores. It writes in your voice. It surfaces what you already know before searching the web. The result is a knowledge system that compounds through discipline, not volume.

Most note-taking systems decay. The vault grows, but old notes go unread, contradictions accumulate, and new sessions repeat work the last session already did. Learning-loop closes that loop. Every session starts by recalling what you already know. Every capture earns its place against quality gates. Every belief that changes gets traced through everything that depends on it.

The outcome is a vault that gets sharper, not heavier. Eight lifecycle hook handlers across five Claude Code event types wire the discipline into the runtime — retrieval fires before you ask, gates fire before promotion, verification catches fabricated sources at write time, web research routes through a config-selected gateway, and corrections propagate when beliefs change. The full roster lives in guide/configuration.md.

One command:

curl -fsSL https://raw.githubusercontent.com/robinslange/learning-loop/main/install.sh | bash

This takes ~3 minutes. It will:

1. Check your platform (macOS arm64 / Linux x86_64 / WSL x86_64 — the platforms with prebuilt ll-search binaries; others need a source build)
2. Ensure Node.js 22+ is available, using your existing version manager if present (nvm, fnm, volta, asdf, mise, n, brew). If none, offers fnm.
3. Add ~/.local/bin to PATH (with a versioned marker in your shell rc, so it's safe to re-run)
4. Install Claude Code if missing
5. Add the superpowers-marketplace and learning-loop marketplace
6. Install both episodic-memory and learning-loop plugins

To inspect first: curl -fsSL https://raw.githubusercontent.com/robinslange/learning-loop/main/install.sh | less

After it finishes, open Claude Code and run /learning-loop:init to configure your vault.

If you'd rather do it yourself or you're on a platform the script doesn't support:

# 1. Install Claude Code: https://docs.anthropic.com/en/docs/claude-code
# 2. Add marketplaces:
claude plugin marketplace add obra/superpowers-marketplace
claude plugin marketplace add robinslange/learning-loop
# 3. Install plugins:
claude plugin install episodic-memory@superpowers-marketplace
claude plugin install learning-loop@learning-loop-marketplace
# 4. Restart Claude Code, then run /learning-loop:init

• episodic-memory (required). Provides semantic recall over past Claude Code conversations, which retrieval, /discovery, /reflect, and /refresh depend on. Install via /plugin install episodic-memory@superpowers-marketplace (lives in obra/superpowers-marketplace).

Full removal (or run /learning-loop:uninstall for a guided version):

/plugin                                    # remove via marketplace UI
claude mcp remove episodic-memory          # only if no other plugin uses it — check first: claude mcp list
rm -rf ~/.claude/plugins/data/learning-loop-learning-loop-marketplace/  # purge captured indexes

To keep commands but silence the hooks, use "disableAllHooks": true in ~/.claude/settings.json. This is a blunt instrument — it disables every plugin's hooks, not just learning-loop's — but it's the mechanism Claude Code exposes for hook suppression. Claude Code's permissions.deny array accepts tool-name rules (Bash(...), Read(...), WebFetch, etc.); there is no documented per-hook deny matcher at this Claude Code version. See the permissions documentation for the current syntax if you want finer control.

learning-loop persists derived indexes locally. What it reads and writes:

The edges database (edges.db) stores note-to-note relationships (backlinks, inferred semantic links, supersessions). The retrieval/ subdirectory holds JSONL logs of every vault and episodic search query. The provenance/ subdirectory records agent-spawn, skill-invoke, and vault-write events. Hook errors land in hook-errors-<YYYY-MM>.jsonl at the plugin data root.

Trust posture. Captured artefacts inherit the trust of their source tools. If a secret is pasted into chat or returned by a misbehaving tool, it can land in plugin data or auto-memory. Run /learning-loop:doctor --redact to scan for likely secrets. Do not paste credentials into chat.

Vault as trust boundary. Retrieved note content is re-emitted into agent context wrapped as untrusted data (Domain 06), so a prompt-injection attempt in a note cannot silently execute. However, operators who let third parties write to their vault inherit prompt-injection risk at the source — the wrapping only contains the blast radius.

Set LL_OFFLINE=1 to suppress every network call the plugin initiates on its own. With it set:

• the SessionStart GitHub update poll (api.github.com) does not fire;
• the binary auto-update download (github.com/<repo>/releases/...) does not run — including the manual /init and /doctor fetch paths;
• web-research source fetches (/verify, /deep-research, /discovery, the source-resolver and claim-checker) short-circuit cleanly instead of attempting an external request and timing out.

Localhost is never gated — the Ollama daemon I use for local offload still works, so an air-gapped box keeps its local model. /doctor reports an Offline mode: ON line so I can confirm the suppression is actually engaged rather than silently skipped.

LL_OFFLINE is orthogonal to LL_REPO (which only repoints the binary download mirror and matters when not offline). One caveat: if I deliberately configure the librarian to use a remote OpenAI-compatible provider (provider.kind: "openai" with a base_url), that is an explicit opt-in egress and is not gated by LL_OFFLINE — the default librarian provider is localhost Ollama, which stays local.

The PostToolUse: Write|Edit|Agent|Skill matcher is intentionally broad. For Write and Edit events the handler runs the full vault-enrichment pipeline (autolink, edge inference, reflect tracking). For Agent and Skill events it runs only lightweight provenance tracking — no vault read, no snapshot load. The matcher breadth is the feature: agent-spawn and skill-invoke events are recorded for auditability, cheaply, by the same dispatcher.

To disable hook tracking entirely without uninstalling, see Disabling parts without uninstalling.

Researching a topic you've partially explored. You run /discovery "caffeine tolerance". The plugin searches your vault first and finds three existing notes on caffeine mechanisms plus a literature note on CYP1A2. It then searches the web, verifies sources against academic APIs, catches a misattributed author on a real PMID, and writes atomic notes in your voice. You see what you already knew, what's new, and where the gaps are.

Catching bad sources before they spread. After a research session produces 12 new notes, you run /verify. It checks every citation mechanically: does the PMID exist, does the DOI resolve, does the author match, does the abstract actually support the claim. One session caught 18 errors across compound profiles because agents had confidently cited papers that didn't say what they claimed.

Capturing without breaking flow. Mid-conversation you realize something worth keeping. /quick-note "junction tables beat comma-delimited membership for M:N" drops it in your inbox. No context switch, no manual filing. /reflect at end-of-session routes it to the right place.

Correcting a belief across everything. You learn that a claim you've been building on is wrong. /rewrite "old pattern" "new pattern" traces every note, auto-memory entry, and episodic record that depends on it, shows you the impact map, and rewrites only what you approve.

All commands are prefixed with /learning-loop: (e.g., /learning-loop:discovery "caffeine").

your-vault/
  0-inbox/          Rough captures, new ideas
  1-fleeting/       Developing notes, partially sourced
  2-literature/     External source captures
  3-permanent/      Complete, sourced, linked, voiced
  4-projects/       Project index notes
  5-maps/           Synthesis and discovery maps
  _system/          Persona and capture rules
  Excalidraw/       Diagrams

• Workflows -- common patterns, session lifecycle, and chaining skills together
• Search -- five-signal hybrid search, reranking, retrieval instrumentation
• Agents -- 20 specialized agents and 19 shared skills
• Federation -- cross-vault knowledge sharing (experimental)
• Configuration -- hooks, injection pipeline, provenance, source verification, cache health
• Resource usage -- token costs, local compute, and what we do to keep it lean
• Cross-platform support -- macOS / Linux / Windows status and known caveats
• Troubleshooting -- common issues and fixes

Built by omit.nz. This plugin is what happens when we codify our own knowledge work. We do the same thing for teams.

Apache-2.0. See LICENSE and NOTICE.