# NikEy's Self-Improving Agent Framework

> Source: <https://gist.github.com/NikEyX/d802bfd4708f3e9d1c6c2b0d8fd36290>
> Published: 2026-11-21 18:27:57+00:00

**Key takeaway:** Giving each agent task its own flow file, read in full before every run, plus a daily 5:00 AM review that fixes only what established instructions already permit and asks the owner before policy changes, keeps agent memory lean and accurate.

|  | AI agents must be programmed, not simply trusted to work correctly from the outset. They lose context over time, struggle to distinguish lasting instructions from incidental details, and may improvise instead of following the way you want them to work. Just as programming evolved from punch cards and assembly language to higher-level languages, we can now program agents in natural language. This framework gives each agent explicit task flows, shared rules and focused memory. Crucially, it includes a self-improving engine that runs every morning at 5:00 AM: it reviews recent work, checks flows and memory for gaps or contradictions, makes corrections already supported by established instructions, and asks the owner before changing policies. The goal is an agent that follows a defined program and systematically improves it over time. | 
|  | Set up your storage folder and memory as a self-improving system, then keep it that way. | 
|  | Your folder holds README.md and flow files in the Google Drive or Dropbox account chosen by your owner. Find an established folder by its saved ID or stable connector-supported locator, never by your name or the folder's name, since names can change. Anyone given access must be able to work from that folder alone, without access to root files or another bot's folder. | 
|  | Goal: every task you do has its own short flow file, you read that file in full before doing the task, every time, your memory stays lean and accurate, and both get a little better every day. | 
|  | 1. Choose storage first | 
|  | - If a folder is already established: Use its saved provider, connected account, folder ID or stable locator, and link. Do not ask again, change accounts, or create another folder. If it is inaccessible, stop and ask your owner to restore access or provide the correct link; never guess by name. | 
|  | - If no folder is established: Check all connected Google Drive and Dropbox accounts for the read, create and update capabilities needed to maintain this system. Distinguish accounts such as Work and Personal. Do not mistake an installed or read-only connector for a usable writable connection. | 
|  | - One usable account: Ask whether to use it. Multiple usable accounts: Ask which specific provider and account to use, listing each separately (for example Google Drive (Work), Google Drive (Personal), Dropbox (Work)). Never choose for your owner. | 
|  | - No usable account: Explain that setup cannot work without a connected Google Drive or Dropbox account with the required permissions, then stop. Do not save elsewhere or claim setup succeeded. | 
|  | - Once your owner selects an account, go to step 7 to establish the folder, then return to step 2. Keep using that provider and account unless your owner explicitly changes them. | 
|  | 2. Read everything first, without changing anything | 
|  | - Read README.md and every file in your folder and its subfolders. | 
|  | - Read any shared instruction files at the selected storage root (for example AGENTS.md or KNOWLEDGE.md), if accessible. Never write to them. | 
|  | - Review your memory, your routines and how you brief helpers, so you know every task you actually do, including tasks no file covers yet. | 
|  | 3. List your flows | 
|  | - A flow is one task you are asked to do or do on a schedule, from start to finish. | 
|  | - Make one list of every task you do, from your files, memory, routines and past chats. | 
|  | - Make one flow per task. If steps differ by platform, system, account type, storage provider or entity, make a separate flow for each variant instead of one flow with sections. | 
|  | - If two tasks have identical steps, make them one flow. | 
|  | 4. Write each flow file | 
|  | - Put each flow in its own file in a flows/ subfolder, named flows/<verb>-<object>.md in lowercase with hyphens. | 
|  | - Each flow file has these sections, in this order: | 
|  | 1. When to use: the requests or triggers that start this flow, and what is out of scope. | 
|  | 2. Before you start: what to read or check first. This includes verifying in the source system itself, not just email or memory, that the task is not already done, plus any inputs or access you need. | 
|  | 3. Steps: numbered, exact steps with menu paths, URLs, settings, field values and decision points ("if X, do Y; otherwise Z"). The last step is "Handoffs": "If X, go to flows/Y.md", for every next flow that can follow. Only a flow that truly ends the chain has no Handoffs step. | 
|  | 4. Checks: how to confirm the result in the source system. Any browser action must be confirmed with a screenshot. | 
|  | 5. Don't: common mistakes, hard limits and things that need approval first. | 
|  | - Every must-do or must-never rule that applies to a flow goes into that flow's Steps or Don't section, even if it is also in rules/. Never rely on memory alone for a rule a flow depends on. | 
|  | - Keep each flow short enough to read in full every time. If a flow grows long, split it. | 
|  | - Wherever a flow depends on a rules/ file, name that file and say to read it at that step. | 
|  | 5. Put shared standards in rules/ | 
|  | - Standards that several flows use (writing and tone, recipients and cc, approvals, naming, file handling, deletion) go in a rules/ subfolder, one topic per file, named rules/<topic>.md. | 
|  | - Flows point to rules files instead of copying them, except for the must-do and must-never rules in step 4. | 
|  | 6. Make README.md the router | 
|  | - README.md has exactly these parts, in this order, and nothing else: | 
|  | 1. This rule, word for word: "Before doing any task, find its flow below, open the flow file and read it in full, every time, even if you have done it before. Never work from memory of a flow. If no flow fits, say so, do the task carefully, and propose a new flow." | 
|  | 2. The heading "This folder", with the storage provider, account, folder ID or stable locator, and link (see step 7). | 
|  | 3. The heading "Scope": one or two lines on what you do and what is out of scope. This is the only place scope is written. Never create rules/scope.md, and never repeat scope in another file; a flow's own "When to use" covers that flow only. | 
|  | 4. A table of every flow with three columns: "When to use (trigger)", "Flow" and "What it does". The trigger says what situation sends you to that flow (an event, a routine firing, a request, a condition with its threshold), not what the flow does. It must match the flow's own "When to use". | 
|  | 5. A list of every rules file with a one-line purpose. | 
|  | - README.md holds no procedures itself. | 
|  | - This order is fixed. If any root file or older file asks for a different README order or a different place for scope, this step wins. Follow it without asking. | 
|  | 7. Make your folder findable without names | 
|  | - Get your folder's stable ID or connector-supported locator and full link. If first establishing an existing folder, find it once, confirm it contains README.md, and record its locator. Thereafter open it by that locator, never by name. | 
|  | - If you have no folder yet, use the provider and account chosen in step 1: | 
|  | 1. Google Drive: Check for an "Agents" shared drive. If it exists and is writable, create your folder at its root, named after you. Otherwise, use an "Agents" folder in the selected account's My Drive (create it if missing), and create your folder inside it. | 
|  | 2. Dropbox: Use an "Agents" folder in the selected account (create it if missing), and create your folder inside it, named after you. Use a shared Dropbox location only if your owner explicitly selected it and you can write there. | 
|  | 3. Inside your folder, create README.md, flows/ and rules/, record its ID or locator and link, and return to step 2. | 
|  | - If you can read your folder but not write to it (for example a copy shared with you), don't attempt writes; keep your notes in memory and list the proposed changes in your report. | 
|  | - For Dropbox, use the connector's supported stable folder ID or locator. If it cannot reliably reopen a folder independently of its name, explain the limitation and ask your owner how to proceed; do not claim it can. | 
|  | - Put the provider, account, folder ID or locator, and link in README.md under "This folder". | 
|  | - Save to memory: "My agent folder is in <provider>, account <account>, folder <ID or locator> (<link>). Always open it using this locator, never by name. Never change provider or account without my owner's approval." | 
|  | - Add the same line to your bot instructions or description, so a copy of this bot shared with someone else still finds the intended folder. | 
|  | - If the locator stops working (for example the folder was moved or access was lost), stop and ask your owner for the correct link instead of guessing by name. | 
|  | 8. Wire flows into routines and helpers | 
|  | - Update every routine prompt to name the exact flow file or files to read first, by provider, account, folder ID or locator, and file path, never by bot or folder name. | 
|  | - Whenever you brief a helper or subagent, tell it which flow file to read first (provider, account, folder locator and file path), and include that file's content or accessible path in the brief. | 
|  | 9. Generic goes in the files, specific goes in memory | 
|  | - Files hold only generic, reusable procedures and standards that anyone doing the same job could follow. | 
|  | - Move everything specific to a location, owner, person, account or moment in time into your memory, then remove it from the files. This includes status notes, open items, dates of changes, who said what, people's names, account IDs, prices paid, "currently X" notes, and deadlines or event dates. | 
|  | - Show values only as placeholders (e.g. <location>, <email>, <amount>). | 
|  | - Never put your owner's personal data, credentials or internal system notes in the files, except the folder connection details required in README.md by steps 6 and 7. | 
|  | 10. Make your folder stand alone | 
|  | - Any rule from a root file that you need goes into the right rules file or flow, in generic form. | 
|  | - Bring over a root rule's content only, never its instructions about file layout, README order or where scope goes. Folder structure always follows steps 4 to 6 of this prompt. | 
|  | - Always include this deletion rule in rules/storage-files.md: "Delete files with a connector that supports deletion or trash in the selected provider and account. For Google shared drives, check that the file can be trashed and use a shared-drive-capable connector. For Dropbox, use its supported delete or trash operation. Verify the target and confirm the result in the source system. Never rename a file to DELETE-<name> or park it in a DELETE folder. If the connector is unavailable or refuses, check memory and past chats for a known fix first; if there is none, tell your owner the file name and exact error." | 
|  | - Remove every reference to files outside your folder. Your files must make complete sense on their own. | 
|  | - Never write to any other bot's folder. | 
|  | 11. Resolve every open question | 
|  | - Collect every "To confirm", "TODO", "open", "unclear" or "?" item across your files. | 
|  | - If your memory, past chats or email answers an item, apply the answer and delete the item. | 
|  | - Never ask about folder structure, file placement or README order; steps 4 to 6 decide those. Ask only about policy and content. | 
|  | - Ask your owner the rest as multiple choice, on one question card with one step per question (a widget with steps, not a prose list): | 
|  | - Each question is one short sentence with the context needed to answer it. | 
|  | - Give 2 to 4 options, each a real, specific choice that reads like a reply. Put your recommended option first and mark it "(recommended)". | 
|  | - Allow a typed answer on every question so your owner can give a different one. | 
|  | - Don't add a "skip" or "other" option; the card already has them. | 
|  | - If you have more than 8 questions, ask the most important 8 first and the rest on a second card after they answer. | 
|  | - Until your owner answers, keep your current behavior. Never change a policy, rule or wording on the strength of your own recommended option. Apply each answer as soon as it comes. A skipped question stays open, and you ask it again later. | 
|  | - When you are done, no open-question sections are left anywhere. | 
|  | 12. Keep it clean | 
|  | - No duplicates between files, except the must-do and must-never rules repeated in flows. | 
|  | - Plain, short wording, with a consistent heading and numbering style in every file. | 
|  | - Delete old files whose content moved into flows/ or rules/, following the storage deletion rule in step 10. | 
|  | - If you ran this cleanup before: delete every DELETE-* file and any DELETE folder in your folder the same way, and replace any rename rule in your files or memory with the storage deletion rule. If you created rules/scope.md, move its content into README part 3 and delete the file the same way. | 
|  | 13. Clean up your own memory | 
|  | - Scope: only your own memories (your profile and journal). Never change shared memories, other bots' memories, or anything else in this step. | 
|  | - Before changing anything, save the exact original text of every memory record you can retrieve to a backup file on your computer (for example /workspace/memory-backups/<your bot name>-<date>.md), so any change can be rolled back. Keep only the last 7 backups. Leave any record you can't back up untouched, and never reconstruct missing or cut-off text. | 
|  | - Remove duplicates, repeated "nothing new" or "no changes" logs, old session and setup chatter, and facts that newer facts clearly replace. Before removing an older fact, confirm the newer one really supersedes it. | 
|  | - Merge overlapping rules into one short, clear record. Drop date wording that adds nothing, but keep dates that matter for deadlines, the order of events, decisions or open items. | 
|  | - Keep every important fact, preference, instruction, exception, uncertainty, distinction between businesses or entities, rejected option and open commitment. Don't invent new rules or infer changes from context. | 
|  | - Generic procedures belong in the files, not in memory (step 9). Once a rule is in the files, drop its memory copy unless it is specific to your owner or a location. | 
|  | - If your memory is already lean, leave it as it is. | 
|  | - Afterwards, compare what you kept and merged against the backup and confirm nothing important was lost. Count the records before and after. | 
|  | 14. Check the logic | 
|  | - References: every file or flow named in README, in any flow or in any rules file exists in your folder. | 
|  | - Listings: every file in flows/ and rules/ is listed in README, and README lists no file that doesn't exist. | 
|  | - Conflicts: no two files give different instructions on the same point (amounts, time windows, wording, steps, or a README trigger against the flow's own "When to use"), and no memory fact contradicts a file. If your owner's newest decision (memory, past chats) settles it, fix the outdated line. If not, leave both and add it to the step 11 questions, quoting both lines and where they are. | 
|  | - Coverage: every task on your step 3 list has a flow and a README trigger, and every situation a flow can end in either hands off to a flow or is a real end. | 
|  | - Flow chain: handoffs have no dead ends and no loops that never finish. | 
|  | - Doability: every step can actually be carried out as written, with the access and tools you have, and every decision point covers both "if" and "otherwise". | 
|  | 15. Verify | 
|  | - For each file: re-read it before writing, write it, then re-read it and confirm the content matches. | 
|  | - Check that README.md has exactly the five parts from step 6, in that order, and that no rules/scope.md exists. | 
|  | - Check that no DELETE-* file or DELETE folder is left in your folder. | 
|  | - Check that every routine names its flow by provider, account, folder locator and file path. | 
|  | - Open your folder by its saved locator from memory and confirm it works in the selected account. | 
|  | 16. Set up daily self-improvement | 
|  | - Create flows/improve-storage-folder.md. Its job is to rerun steps 2 to 15 of this prompt every day on the existing folder and memory: re-read everything (files, memory, routines and the past day's chats), clean up memory, check the logic, and fix whatever the files and your owner's newest decisions already settle. Policy, amounts and customer-facing wording are never changed on your own judgment; they become step 11 questions. | 
|  | - Create a routine that runs every day at 5:00 AM in your owner's time zone. It opens your existing folder in the saved provider and account by locator, reads README.md and flows/improve-storage-folder.md in full, and follows it. Never create a replacement folder or change storage accounts during a routine. | 
|  | - If the run improved anything, it sends your owner a short summary: one line per file changed, and the memory record count before and after if memory changed, plus any open questions as the step 11 card. If nothing needed improving, it sends nothing. | 
|  | - If you only have read access to the folder (for example a copy shared with you), don't write files; keep your notes in memory and include the fixes you would make in the summary. | 
|  | - If you already have a routine that reconciles your folder with shared storage files (for example a daily reconcile with AGENTS.md), keep it but move it to weekly, and make it flag-only: if something differs, tell your owner what differs and ask whether to update your own files; change nothing until they say yes; if nothing differs, send nothing. If you have no such routine, don't add one. | 
|  | - Add both routines to the README flow table with their triggers. | 
|  | 17. Save the habit to memory | 
|  | - Save to memory: "Before any task, open my agent folder using its saved provider, account and folder locator, and read the task's flow file in full, every time. Never work from memory of a flow." | 
|  | 18. Report back to your owner | 
|  | - Your storage provider, connected account, folder ID or stable locator, and link. | 
|  | - One line per file: new, changed or deleted, and what it covers. | 
|  | - Any file you could not delete, with the exact error. | 
|  | - The list of flows, and which routines now point to which flow, including the new 5 AM self-improvement routine. | 
|  | - Memory: record count before and after, where the backup is, and a short list of what moved between files and memory. | 
|  | - Then send the open questions as the multiple-choice card from step 11, as the last thing in your report, and say nothing changes until your owner answers. |
