- "tinymem_protocol": "# TINYMEM AGENT CONTRACT\n\n## Hard Enforcement Specification for Repository-Aware AI Agents\n\nThis contract governs **all repository-related behavior**.\n\nIt is **authoritative**, **mandatory**, and **self-validating**.\nNon-compliance invalidates the response by definition.\n\n---\n\n## 0. Binding Definitions\n\n**Repository-related request**\nAny request that touches code, files, documentation, architecture, configuration, tasks, planning, or repository state.\n\n**TinyMem command**\nA real, externally executed memory tool invocation (`memory_query`, `memory_recent`, `memory_write`, etc.).\nInternal recall, inference, or chat reconstruction does **not** qualify.\n\n**Task Authority**\nThe `tinyTasks.md` file in the project root is the **single source of truth** for task state.\nFile operations (`read_file`, `write_file`, `replace`, `cat`) on this file are the only valid way to check or update tasks.\n\n**Valid response**\nA response that demonstrates protocol compliance through observable actions and explicit declarations.\n\n---\n\n## 1. Absolute Precondition (Hard Gate)\n\n**Before producing ANY repository-related response, the agent MUST execute at least one TinyMem command AND check task state.**\n\nThis is a hard gate.\n\nIf no TinyMem command is executed OR `tinyTasks.md` is not read:\n\n* The response is invalid\n* The agent must not proceed\n* Partial or \"best-effort\" responses are forbidden\n\nThere are no exceptions.\n\n---\n\n## 2. Proof-of-Execution Requirement (Anti-Circumvention)\n\nEvery valid repository-related response MUST include **explicit proof** of:\n\n* At least one TinyMem tool invocation\n* At least one read of `tinyTasks.md` (e.g., `cat tinyTasks.md`) OR confirmation that it does not exist\n\nSilent execution is forbidden.\nMissing proof invalidates the response.\n\n---\n\n## 3. Mandatory Execution Order (Non-Reorderable)\n\nThe following steps MUST be executed **in strict order**.\nSkipping, merging, or reordering steps is a violation.\n\n---\n\n### Step 1: Memory Recall (MANDATORY, FIRST)\n\nThe agent MUST execute **at least one** of the following **before any reasoning**:\n\n```\nmemory_query(\"\")\nmemory_recent()\nmemory_query(\"\u003cspecific topic\u003e\")\n```\n\nRules:\n\n* This must be a real tool execution\n* Assumed recall is forbidden\n* Chat history does not count\n\nNo recall → stop immediately.\n\n**Result declaration (one and only one):**\n\n* **\"Relevant memory found and applied [to context/decision/implementation].\"** (with evidence)\n* **\"Memory queried. No relevant memory found.\"**\n\nOmission or paraphrasing invalidates the response.\n\n---\n\n### Step 2: Task Authority Lock (MANDATORY)\n\nThe agent MUST read `tinyTasks.md` to check for existing tasks.\n\nRules:\n\n* The file MUST be read before any action\n* Memory MUST NOT override task state\n* Task state MUST NOT be inferred\n\nFor any non-trivial, multi-step, or stateful request, the agent MUST:\n\n1. Create or update `tinyTasks.md`\n2. Resume from the **first unchecked subtask**\n3. Update tasks **as execution progresses**\n4. Mark tasks complete **only when actually finished**\n\nRequired structure (no deviations allowed):\n\n```md\n# Tasks – \u003cGoal\u003e\n\n- [ ] Top-level task\n - [ ] Atomic subtask\n - [ ] Atomic subtask\n```\n\nFailure to update tasks is a protocol failure.\n\n**Result declaration (one and only one):**\n\n* **\"Task state queried. No pending tasks. [New task created].\"** (if new task made)\n* **\"Task state queried. Resuming task from subtask: [description].\"** (if resuming)\n* **\"Task state queried. No tasks exist.\"** (if none)\n\nOmission or paraphrasing invalidates the response.\n\n---\n\n### Step 3: Autonomous Repair (The Ralph Loop) — WHEN APPLICABLE\n\nFor complex, iterative tasks requiring verification (e.g., fixing failing tests), the agent SHOULD invoke `memory_ralph`.\n\n**Control Transfer Contract:**\n1. Once `memory_ralph` is invoked, control transfers to tinyMem.\n2. The agent may not execute individual shell commands or declare success until the loop returns.\n3. Termination is controlled solely by **Evidence Evaluation**.\n\n**Execution Phases:**\n- **Execute**: tinyMem runs the verification command.\n- **Recall**: On failure, tinyMem retrieves relevant memories and failure patterns.\n- **Repair**: tinyMem uses its internal LLM to apply code fixes based on context.\n- **Evidence**: Success is declared only if all evidence predicates pass.\n - **Format Requirement**: Predicates MUST use the `type::content` format (e.g., `test_pass::cargo test`, `file_exists::path/to/file`).\n\n**Safety Rules:**\n- Agents MUST provide `forbid_paths` for sensitive directories.\n- Agents SHOULD set `max_iterations` to prevent runaway token usage.\n- After `memory_ralph` completes, update `tinyTasks.md` to update the task status before proceeding.\n\n---\n\n### Step 4: Execution Phase\n\nOnly after Steps 1–3 are complete may the agent:\n\n* Perform the requested work\n* Modify code, documentation, or plans\n* Propose or apply decisions\n\n**During execution:**\n\n* If a task is active, update `tinyTasks.md` to mark progress after each major milestone\n* Update task descriptions or status to reflect current state\n* Never leave a task in progress with stale information\n\nAny execution before this point invalidates the response.\n\n---\n\n### Step 5: Durable Memory Writeback (MANDATORY WHEN APPLICABLE)\n\nIf the response introduces, confirms, or corrects **durable knowledge**, the agent MUST write it to TinyMem **before concluding**.\n\n**Durable knowledge is defined as ANY of:**\n\n* A decision was made (e.g., \"chose to use Redis instead of in-memory cache\")\n* An assumption was corrected or confirmed (e.g., \"discovered that X works differently than documented\")\n* A constraint or invariant was established or clarified\n* An architectural rule was applied or amended\n* The user explicitly confirmed something (e.g., \"yes, this is the desired behavior\")\n* A technical discovery with implications for future work (e.g., \"ringbuf API requires X pattern\")\n\n**If no durable knowledge was produced, the agent MUST state verbatim:**\n\n\u003e No durable memory write required for this response.\n\nMissing or altered wording invalidates the response.\n\n---\n\n### Step 6: Task Completion (MANDATORY WHEN APPLICABLE)\n\nIf a task was being tracked:\n\n* Verify the current task state in `tinyTasks.md`\n* Update `tinyTasks.md` to mark the task or subtasks as `[x]` (completed)\n* If subtasks remain, update the task description to reflect next unchecked subtask\n\n---\n\n### Step 7: End-of-Response Self-Validation (MANDATORY)\n\nThe response MUST end with an explicit checklist confirming all of the following:\n\n- [ ] TinyMem command executed (tool invocation visible)\n- [ ] Memory integrated or explicitly confirmed empty\n- [ ] `tinyTasks.md` read and updated if applicable\n- [ ] No completed tasks left unchecked\n- [ ] No unchecked tasks remain unless explicitly blocked\n- [ ] Durable knowledge written to memory OR \"No durable memory write required\" stated\n\nIf any item cannot be affirmed, the agent MUST continue execution.\nThe response may not terminate.\n\n## tinyTasks Auto-Creation\n\ntinyTasks.md creation is a system concern; task authoring is a human concern. The system may proactively create the ledger for intent, but only a human can introduce the unchecked tasks that signal intent. tinyMem may automatically create `tinyTasks.md` when multi-step work is implied, but task intent is recognised only when a human defines unchecked tasks within it.\n\nAuto-creation is mechanical and is triggered whenever **any** of the following occur:\n\n1. A multi-step action is requested (e.g., “Refactor…”, “Implement…”, “Add support for…”, “Fix these issues…”, “Build a system that…”).\n2. The agent would otherwise refuse because `tinyTasks.md` is missing.\n3. A task-related CLI or MCP command is invoked (for example, `tinymem dashboard`).\n\nEvery auto-created file must be intentionally inert:\n\n* Explicitly non-authorising (it tells the human no work is authorised until someone edits it).\n* Human-edit required before work can resume.\n* Machine-detectable as “no intent yet” (e.g., the title remains `# Tasks — NOT STARTED`).\n\nA canonical auto-created template:\n\n```\n# Tasks — NOT STARTED\n\u003e\n\u003e This file was created automatically because a multi-step workflow\n\u003e may be required.\n\u003e\n\u003e No work is authorised until a human edits this file and defines tasks.\n\n## How to proceed\n\n1. Replace the title above with a concrete goal\n2. Add one or more unchecked tasks (`- [ ]`)\n3. Save the file\n4. Resume work\n\n## Tasks\n\n\u003c!-- No tasks defined yet --\u003e\n```\n\nThe updated invariant is:\n\n\u003e Presence of `tinyTasks.md` is not intent. Presence of unchecked, human-authored tasks is intent.\n\nTask memory is synchronized only when all of the following are true:\n\n1. `tinyTasks.md` exists.\n2. It contains one or more unchecked tasks.\n3. The file has been modified since the last sync.\n4. The tasks are parse-valid.\n\nWhen `tinyTasks.md` exists but contains no unchecked entries, the agent must refuse multi-step execution and clearly respond: “Task file exists but no tasks are defined. Please edit `tinyTasks.md` to proceed.” If unchecked tasks exist, the agent may create task memory, resume incremental work, and enforce completion tracking.\n\n---\n\n## 4. Error Handling (Fail Closed)\n\nIf any tool operation fails (TinyMem, File I/O, Bash, etc.):\n\n* The failure MUST be explicitly declared with the tool name and error\n* Memory guarantees are considered degraded\n* Task state cannot be assumed\n* Planning, restructuring, or irreversible changes are forbidden\n* Only safe, local, reversible actions are allowed\n* Attempt to retry the failed operation up to 2 times\n* If still failing, STOP and ask the user for manual intervention\n\nSilent failure is a critical violation.\n\n---\n\n## 5. Invalid Actions (Automatic Failure)\n\nAny of the following immediately invalidate the response:\n\n* No TinyMem command executed\n* No task state query executed (reading `tinyTasks.md`)\n* No proof of execution shown\n* Claiming memory state without querying\n* Inferring task state (saying \"I assume there are no tasks\")\n* Ignoring active tasks (unchecked items in `tinyTasks.md`)\n* Declaring completion with unchecked tasks\n* Writing speculative, temporary, or reversible information to memory\n* Ending the response without explicit self-validation checklist\n* Task marked complete when subtasks remain unchecked\n\n---\n\n## 6. Enforcement Invariant (Unbreakable)\n\n\u003e A repository-related response without TinyMem and `tinyTasks.md` operations is not a response. It is a failure.\n\nMemory is mandatory.\nTask state is authoritative.\nInference is forbidden.\nExecution state lives in files, not in agent inference.\n\n---\n\n**End of Protocol**"
0 commit comments