{
  "markdown": "# loop-and-gate-foundation\n\n[![Listed on ClaudePluginHub](https://www.claudepluginhub.com/badge/slogsdon-loop-and-gate-foundation)](https://www.claudepluginhub.com/plugins/slogsdon-loop-and-gate-foundation?ref=badge)\n\nAn AI agent that **remembers** — and gets better at working with you over\ntime. Built on [Claude Code](https://claude.com/claude-code) and\n[Obsidian](https://obsidian.md), using nothing but plain markdown files and\ntwo small shell scripts.\n\nNo prior experience with agents, loops, or Obsidian required. This README\nassumes you're starting from zero.\n\n> **Never used a terminal?** Read **[GETTING-STARTED.md](GETTING-STARTED.md)** —\n> a download-and-click path using the Claude desktop app, no terminal at all.\n> The setup below is the terminal (`git clone`) path for people who prefer it.\n\n## What this is / what it's not\n\n**It is** a memory-and-self-improvement layer for [Claude Code](https://claude.com/claude-code),\nstored as plain markdown in an Obsidian vault. You run normal interactive\nsessions; it captures facts, writes an honest self-review each time, and edits\nits own skills from lessons that repeat.\n\n**It is not** a model or a fine-tune (the weights never change — the files\naround the model do), a hosted service or database to stand up (no server, no\nvector DB — just files and two shell scripts), or a prompt library you paste\nfrom (it runs the loop for you).\n\n## The problem this solves\n\nEvery AI chat session starts from a blank slate. You explain your project,\nyour preferences, your constraints — and when the session ends, all of it\nevaporates. Tomorrow you explain it again.\n\nThis system fixes that with a simple idea: **the agent writes things down.**\n\n- Facts it learns go into notes (a \"second brain\" it can read back later)\n- What happened each day goes into a daily log\n- After every session, it writes an honest self-review: what worked, what\n  didn't, and one lesson\n- Periodically, repeated lessons get applied as *actual edits to its own\n  instructions* — so next week's agent is measurably sharper than today's\n\nThe AI model itself never changes. What improves is everything around it:\nits notes, its instructions, its habits. That's what \"self-improving\" means\nhere — the system compounds, one session at a time.\n\n## The pieces (60-second tour)\n\n**Obsidian** is a free note-taking app that stores notes as plain markdown\nfiles in a folder (a \"vault\"). Perfect for agent memory: you can read\neverything the agent knows, edit it, and watch it grow — in a nice UI with\nlinks between notes. (Obsidian is optional — the files are just markdown and\nwork fine without it.)\n\n**Claude Code** is Anthropic's command-line AI agent. It can read and write\nfiles, run commands, and follow instruction files called **skills**.\n\n**A skill** is just a markdown file that teaches Claude a repeatable\nprocedure. This repo's skills:\n\n| Skill | What it does |\n|-------|--------------|\n| `setup` | First-run only: places and scaffolds your vault (runs the bundled setup script on either the clone or plugin path) and records its location |\n| `session-start` | Loads memory at the start of a session (the index, the latest daily log, the latest reflection) |\n| `capture` | Saves a durable fact to the Knowledge folder and indexes it |\n| `inbox-triage` | Clears `vault/Inbox/` — the raw thoughts you dumped from your phone — sorting each into a fact, an idea, a task, or noise, with your confirmation |\n| `profile-interview` | Interviews you to build a voice profile (how you write) and a taste profile (how you judge), so the agent can sound like you and make calls you'd agree with |\n| `reflect` | Ends a session: logs what happened + writes a self-review with one lesson |\n| `verify` | Checks a claim using a fresh subagent that never saw the work — it gets the claim and the evidence files, and is asked to disprove it |\n| `improve` | Applies lessons that have come up repeatedly — after `verify` has failed to kill them — by editing the skill files themselves |\n| `loop` | For bigger goals: your session becomes the orchestrator — it breaks the goal into tasks and dispatches a fresh subagent per iteration, verifying each result before it's committed |\n| `add-kits` | Offers to install the rest of the stack — the Build, Grow, and Accountability kits and each one's swappable pipeline — every piece a gated, declinable choice |\n\n**The loop** ties it together: one interactive Claude Code session = one\niteration. Open Claude Code in this folder and the SessionStart hook loads\nmemory, and the operating rules in `CLAUDE.md` run the protocol (load memory → work → save\nlearnings → reflect). When you're done, exit. Next time, a fresh session\npicks up where the *files* left off. Only the memory files carry over between\nsessions — that's deliberate, it keeps the agent focused and reliable.\n\n## The memory layout\n\n```\nvault/\n├── MEMORY.md        ← the index: who you are, active goals, lessons,\n│                      one line per knowledge note. Kept SHORT on purpose.\n├── Inbox/           ← raw thoughts you dump from your phone, cleared by\n│                      the inbox-triage skill (see \"Capturing on the go\")\n├── Profiles/        ← how you write + how you judge, built by\n│                      profile-interview (see \"Teaching it your voice\")\n├── Daily/           ← one note per day: what happened in each session\n├── Knowledge/       ← one note per topic: facts the agent has learned\n└── Reflections/     ← the agent's self-reviews and improvement proposals\n```\n\nThree kinds of memory, if you like the theory: **episodic** (Daily — what\nhappened), **semantic** (Knowledge — what's true), and the current session's\ncontext window (working memory, discarded every iteration). The index keeps\nit all findable without loading everything.\n\n## Prompt caching (why MEMORY.md only changes at session end)\n\n`MEMORY.md` is the most-read file in the system — the hook injects it at the\nvery top of every session. Claude Code automatically caches that stable\nprefix, so as long as the file doesn't change mid-session, every message in\nthe session reloads it from cache: cheaper and faster.\n\nThat's why the system enforces one rule everywhere: **MEMORY.md is read at\nsession start and written once at session end** (when the agent reflects, or\nwhen an improvement pass finishes). Facts captured mid-session go into\n`Knowledge/` notes immediately; their index lines wait for the close-out.\nOne write per session = maximum cache hits = lower cost and faster sessions\nover time.\n\n## Install\n\nTwo ways in: **clone** for the full self-improving loop (the skills are your\nworking copy, so `improve` can edit them), or install as a **plugin** to run it\neverywhere. *(No terminal at all? Use [GETTING-STARTED.md](GETTING-STARTED.md).)*\n\n### Clone — terminal path (5 minutes)\n\nYou need: a Mac or Linux machine, [Node.js](https://nodejs.org), and a\nClaude subscription or API key.\n\n```bash\n# 1. Install Claude Code (skip if you have it)\nnpm install -g @anthropic-ai/claude-code\n\n# 2. Clone this repo\ngit clone https://github.com/slogsdon/loop-and-gate-foundation.git\ncd loop-and-gate-foundation\n```\n\nThen open Claude Code (`claude`) and run the **`setup` skill** — just ask\n*\"set up my vault\"* (or `/setup`). It asks where your vault should live\n(recommending your Obsidian iCloud folder on macOS, so the same vault syncs to\nObsidian on iPhone and iPad for free), scaffolds it, and records the path so the\nmemory hook finds it every session. `/setup` is the front door on both the clone\nand plugin paths — one thing to learn.\n\n**Advanced / non-interactive:** run the underlying script directly,\n`./scripts/setup.sh ~/my-vault`, e.g. from dotfiles or CI. Without a path it\nauto-picks a location (iCloud on macOS, else `~/second-brain`) rather than\nasking — pass the path to stay in control.\n\n**Power move:** git-init the vault (setup prints the command) so every change the\nagent makes to what it knows becomes tracked and reversible.\n\nOptional but nice: install [Obsidian](https://obsidian.md), then\n\"Open folder as vault\" → pick your vault folder. Now you can watch the\nagent's brain grow.\n\n### Or install as a plugin (no clone)\n\n```\n/plugin marketplace add slogsdon/loop-and-gate-foundation\n```\n\nEnable it, then run the **`setup` skill** once to place your vault — just ask\n*\"set up my vault\"* (or `/setup`). Unlike the clone path, you have no\n`scripts/setup.sh` in your working directory here; the script ships in the\nplugin cache, and the skill finds and runs it for you. Then start any session —\nthe SessionStart hook and all nine skills load globally. On this path the hook\nalso injects the operating rules (`CLAUDE.md`) into every session: a plugin's\n`CLAUDE.md` isn't on Claude Code's load path, so unlike a clone it can't\nauto-load — a second SessionStart hook delivers it instead.\n\n**One limitation, by platform.** The `improve` skill rewrites its own skills as\nit learns. That self-editing only persists in a **clone**, where the skills are\nyour working copy. Installed as a **plugin**, skills live in a read-only cache,\nso `improve` still evolves your memory (`MEMORY.md`, reflections) but not the\nskill files themselves. Windows plugin users may also need developer mode for\nthe compatibility symlink. Clone for the full self-improving loop; install the\nplugin if you just want to run it everywhere.\n\n## Usage\n\n```bash\n# Start a session — the hook loads memory + the operating rules that run the protocol\nclaude\n```\n\nThen talk to it. A few things to try, by name:\n\n```\n\"Get to know me: ask about my project and preferences, then save what you learn\"\n\"Research the best CRM for a 3-person consultancy and write a comparison\"\n\"Build my voice profile\"                              → runs profile-interview\n\"Triage my inbox\"                                     → sorts vault/Inbox/\n\"Add the rest of the stack\"                           → runs add-kits\n\"Run the improve pass: apply the reflections that have earned it\"\n```\n\nWith no goal, it picks up open items from the last daily note. The full\nwalkthroughs are just below — [Your first session](#your-first-session) and\n[Daily use](#daily-use).\n\n## Your first session\n\nOpen Claude Code in this folder, then give it a goal:\n\n```bash\nclaude\n# then, in the session:\n# \"Get to know me: ask about my current project and preferences, then save what you learn\"\n```\n\n(Or open the folder in the Claude desktop app or your IDE — same result;\nthe hook does the priming — memory plus the operating rules.) It's a normal interactive session —\nyou can talk to it, steer it, interrupt it. What happens:\n\n1. A session-start hook injects `vault/MEMORY.md` (nearly empty right now)\n   plus the latest daily note and reflection — automatically, every session\n2. It asks you questions, and **captures** the answers into\n   `vault/Knowledge/` notes\n3. When you wrap up, it **reflects**: logs the session to `vault/Daily/`,\n   writes its first self-review to `vault/Reflections/`, and commits\n4. Exit the session (Ctrl+D or /exit)\n\nOpen the vault and look around. Everything the agent \"knows\" is right there\nin readable markdown. That transparency is the point.\n\n## Daily use\n\nOpen Claude Code in this folder (`claude`, the desktop app, or your IDE) and\ngive it a goal — or none:\n\n```\n\"Research the best CRM options for a 3-person consultancy and write up a comparison\"\n```\n\nWith no goal, it picks up open items from the last daily note. The\nSessionStart hook loads memory and the operating rules run the protocol either way.\n\nOne session = one iteration of the loop. Work until done or blocked, let it\nreflect, exit. The next session starts fresh and continues from what the\nfiles say — you can run one iteration a day or ten in a row.\n\nFor a goal too big for one session, ask for the **loop skill**\n(\"run the loop on: <goal>\"). Your session stays as the orchestrator and\nhuman gate. Each iteration runs in a subagent with a fresh context, and\nnothing lands in memory until the orchestrator verifies it. Best of both:\nclean-slate iterations *and* you watching every step.\n\n## Capturing on the go\n\nThe best ideas don't wait until you're at your desk. This is where Obsidian's\nmobile app earns its keep — it's the same vault in your pocket. Drop a thought\ninto `vault/Inbox/inbox.md` from your phone (one line, no structure) and it\nsyncs back to your machine. The system doesn't care how it arrives: Obsidian\nSync, iCloud, or a plain `git pull` all work, since the inbox is just a file.\n\nNext session, ask the agent to **triage the inbox**. It reads each thought,\nsorts it into a fact, an idea, a task, or noise, and — this is the part that\nmatters — shows you its sorting and waits for your yes before it files\nanything. You capture in two seconds at a red light. The agent does the filing\nlater, on your terms. Nothing gets filed you didn't approve, and nothing gets\ndropped you didn't see.\n\nNo app to build, no server to run. Obsidian mobile plus Claude Code on your\nmachine covers quick capture — but you're not limited to capture on the go.\nRunning full sessions from your phone or tablet is the next section.\n\n## Working across devices\n\nQuick capture from your phone is the lightweight path. The full version: **run\nreal Claude Code sessions from any device** — phone, tablet, desktop — all\nagainst the same vault. Two Claude Code features make it work, and the vault\nsyncs underneath them.\n\n**Remote Control** lets a session running on your desktop be driven from any\nother Claude app — the web app, the mobile app, your tablet. It's off by\ndefault; turn it on once so it's the default for every session:\n\n```bash\nclaude --remote-control        # just this session\n# make it permanent in settings.json:\n#   \"remoteControlAtStartup\": true\n# or in the Claude desktop app:\n#   Settings → Claude Code → enable remote control by default\n```\n\nNow you can start a session at your desk and keep steering it from the couch —\nsame session, same vault, same skills.\n\n**Dispatch** is the other half, for starting work when you're away from the\nmachine. From the Claude mobile app (Cowork tab), hand it a task; it spins up a\nCode session on your desktop and pushes you a notification when it's done or\nneeds a decision. You delegate from your phone, the work runs where your files\nlive — even from the beach.\n\nThe point of both: the session always runs on the machine that holds your\nvault, so your memory and skills are available anywhere without copying\nanything around.\n\n### Syncing the vault underneath\n\nSessions run on your desktop; the *vault* has to reach your other devices so\nObsidian — and any quick capture — sees the same files.\n\n- **macOS + iOS/iPadOS:** iCloud, which `setup.sh` picks by default. One gotcha\n  for larger vaults — tell iCloud Drive to **keep the Obsidian folder\n  downloaded** on each device (phone, tablet, desktop). Otherwise iCloud\n  offloads it and you hit long sync delays and re-indexing when you open it.\n- **Android or Windows:** iCloud isn't an option. Use **Obsidian Sync** (paid,\n  turnkey), the community **git plugin** (free, occasionally flaky), or a\n  Dropbox / OneDrive folder. The vault is just files — anything that syncs a\n  folder works.\n\n**Mind the sync delay.** Sync isn't instant. Jot a note on your phone, then\nimmediately ask a desktop session to read it, and it may report the note\nmissing (brand-new) or stale (not synced yet). That's lag, not data loss — give\nit a few seconds. Editing a note on mobile while a desktop session writes to it\nis generally fine; if you want to be safe, finish on one device before you pick\nit up on another.\n\n### Running more than one session at once\n\nIf you keep more than one session going, git is what stops them clobbering each\nother — two sessions committing to the same repo can bury one's changes under\nthe other's. The clean fix is to **run each session in its own git worktree**,\nso each works on an isolated copy and merges deliberately. The catch:\n**delete worktrees when you're done**, or duplicate copies of your work quietly\neat disk. Keep commits and pushes to your backup remote on **one machine** (the\ndesktop) so history has a single writer.\n\n**This applies to every kit, not just the Foundation.** The Build, Grow, and\nAccountability kits all read and write the same vault, so the same sync and\nworktree discipline covers them — there's nothing kit-specific to learn.\n\n## Teaching it your voice\n\nRun **profile-interview** once (\"build my voice profile\") and the agent\ninterviews you — one question at a time — about how you write and how you judge\ngood work. It writes two reference docs into `vault/Profiles/`: a voice profile\n(so anything it drafts can sound like you) and a taste profile (so it has a\nstandard to point at when it has to make a call you'd normally make yourself).\nRe-run it anytime to sharpen either one. It merges rather than overwrites.\n\n## Add the rest of the stack\n\nFoundation is the ground floor. On top of it sit three more kits — **Build**\n(ship software through judgment gates), **Grow** (take it to market), and\n**Accountability** (your own follow-through) — all in the same marketplace you\nalready added. Run **add-kits** (\"add the rest of the stack\" or `/add-kits`) and\nit offers each one, then offers each kit's build/grow pipeline separately. Every\npiece is a gated, declinable choice: the kits are optional and the pipelines are\nswappable, so if you bring your own tools you just say no and keep your setup.\nIt's safe to re-run — it skips whatever you've already installed — so you can add\none kit now and the rest whenever.\n\n## The self-improvement part\n\nAfter you've run a handful of sessions, start a session and ask for an\nimprovement pass:\n\n```\n\"Run the improve pass: apply the reflections that have earned it.\"\n```\n\nThe agent reads all the accumulated self-reviews and applies the lessons that\nhave **come up more than once** — by editing the skill files, the memory\nindex, or the config. It walks you through each change as it makes it, and\ncommits so there's a diff:\n\n```bash\ngit show   # review what the agent changed about itself\n```\n\nWhy only repeated lessons? One bad session is noise. The same problem twice\nis a pattern. This gate is what separates self-improvement from an agent\nthrashing its own instructions. And why the git commit? So *you* stay in the\nreview loop — every change the agent makes to itself is a diff you can read\nand revert.\n\nThat's the whole trick, and it compounds: sharper instructions → better\nsessions → better reflections → sharper instructions.\n\n## Dials you can turn\n\n- `config.yaml` → `vault` — point at a different vault (e.g. your\n  real Obsidian vault) once you outgrow the starter one\n- `CLAUDE.md` — the agent's standing behavior rules, edit to taste (the\n  improve skill will also propose edits here over time). Auto-loaded on a clone;\n  on a plugin install the SessionStart hook injects it, since a plugin's\n  `CLAUDE.md` isn't on Claude Code's load path\n\n## FAQ\n\n**Does the AI actually learn?** The model's weights never change — no\ndeployed system does that. What changes is its *environment*: notes,\ninstructions, config. Functionally, it remembers and improves. Mechanically,\nit's markdown files getting better.\n\n**What if it writes something wrong into memory?** Edit the file — it's\nmarkdown. Or `git revert`. Every memory change is a commit.\n\n**Can it mess up its own skills?** The improve skill has guardrails (only\nrepeated signals, each one then checked by a fresh agent that never saw the work,\nno gate-weakening, everything committed for your review), and `git revert` undoes\nany bad edit.\n\n**Do I need Obsidian?** No — it's a viewer. The system is just files.\n\n## Contributing\n\nIssues and pull requests are welcome. Start with\n[CONTRIBUTING.md](CONTRIBUTING.md) — it covers how to report bugs, how to\npropose skill or hook changes, and the PR conventions. One thing worth knowing\nup front: the `improve` gate (only repeated lessons, everything committed for\nreview, no self-weakening) is load-bearing by design, so PRs that weaken it will\nbe declined. See also the [Code of Conduct](CODE_OF_CONDUCT.md) and the\n[security policy](.github/SECURITY.md).\n\n## Going deeper\n\n- [Loop & Gate](https://shane.logsdon.io/loop-and-gate/) — the whole stack this is the\n  Foundation of: the mental model, all four pieces, and how to install them together\n- `ARCHITECTURE.md` — the architecture, the research behind each decision, and\n  what was deliberately left out\n- Lilian Weng's [LLM Powered Autonomous Agents](https://lilianweng.github.io/posts/2023-06-23-agent/)\n  — the canonical writeup of agent planning, memory, and reflection\n- Andrej Karpathy's [\"system prompt learning\"](https://x.com/karpathy/status/1921368644069765486)\n  — the idea this repo implements literally: an agent that edits its own\n  instructions\n",
  "bytes": 20764,
  "sha": "a5b61e439e6b86ee0352d899a8a4bd97d7548d9a5f902c9cc72c0e1b61436f4e",
  "repo_slug": "slogsdon/loop-and-gate-foundation",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_slogsdon_loop_and_gate_foundation_loop_a_bd204089/readme"
}