Better agent text (Release v0.8.4)

Author: daverage

AGENTS.md

@@ -1,27 +1,26 @@
 **Start of tinyMem Protocol**
-You operate under TinyMem governance.
+You operate under TinyMem governance. This protocol is MANDATORY.
 
-If a request would create files, change files, tasks, or memory:
-- use TinyMem MCP tools when available; otherwise use standard file tools
-- do not assume state
-- do not claim changes unless a tool call succeeds
+### 1. The Workflow
+1. **Observe:** Call `memory_query` or `memory_recent` before any mutation to avoid duplicates or conflict.
+2. **Sequence:** If a task has 2+ steps, externalize them to `tinyTasks.md` (use `task_add`).
+3. **Mutate:** Use standard tools to edit files. Never assume state.
+4. **Persist:** Call `memory_write` immediately after a successful mutation. **NEVER** claim a change until this tool succeeds.
 
-If a tool call is blocked or rejected, adapt and retry.
-Otherwise, respond normally.
+### 2. Guardrails
+- **Fail Closed:** If a tool fails or state is ambiguous, STOP and ask the user.
+- **Tool Authority:** Prefer MCP tools (`memory_*`) over CLI commands when available.
+- **Evidence:** Facts require evidence; decisions require rationale.
 
-**TinyMem tool reference**
-- `tinymem health` — verify the database, schema, and connectivity before any mutation.
-- `tinymem doctor` — run a deeper diagnostic that reports configuration or health issues with storage, recall, or authorities.
-- `tinymem stats` — check current memory/task counts and pass/fail rates to decide whether to update or run additional tooling.
-- `tinymem dashboard` — view or refresh the visual task/memory status when you need awareness of progress or blockers.
-- `tinymem query "<term>"` — search the existing memory store for a term that might affect your next edit.
-- `tinymem recent` — fetch the latest entries so you can reference what tinyMem just learned.
-- `tinymem write --type <type>` — persist a decision, note, or claim once you have collated the facts.
-- `tinymem mcp` — start the stdio server that accepts the `memory_*` tool calls described below.
+### 3. Tool Reference (MCP)
+- `memory_query`: Search contextual memory. **Required** before mutations.
+- `memory_recent`: Fetch latest entries for immediate context.
+- `memory_write`: Persist facts/decisions. **Required** after mutations.
+- `task_add`: Add/Update `tinyTasks.md` entries. **Required** for multi-step work.
 
-- `memory_query` — search contextual memory; required before mutations only in GUARDED/STRICT modes. In PASSIVE mode, mutations proceed without prior recall.
-- `memory_recent` — fetch the most recent memories if you need to reference immediately preceding work.
-- `memory_write` — persist a fact/decision/note; never claim a repository change without this tool concluding successfully.
-- `task_add` — create tinyTasks.md if missing and append a task in one call; use this instead of creating the file manually.
+### 4. Tool Reference (CLI)
+- `tinymem health/doctor`: Verify DB/Config before starting work.
+- `tinymem stats/dashboard`: Check progress and health metrics.
+- `tinymem write/query/recent`: CLI equivalents of MCP tools.
 
-**End of tinyMem Protocol**
+**End of tinyMem Protocol**

CRUSH.md

@@ -2,11 +2,10 @@
 You operate under TinyMem governance.
 
 If a request would change files, tasks, or memory:
-- use TinyMem MCP tools
+- use TinyMem MCP tools when available; otherwise use standard file tools
 - do not assume state
 - do not claim changes unless a tool call succeeds
 
-Tool calls are the only way to affect reality.
 If a tool call is blocked or rejected, adapt and retry.
 Otherwise, respond normally.
 **End of tinyMem Protocol**

GEMINI.md

@@ -130,25 +130,18 @@ If **Task Identification** occurs:
 
 If `tinyTasks.md` does NOT exist:
 
-* Create the inert template
-* Populate it with a proposed task list
-* STOP
-* Request the human to review, edit, reorder, or approve the proposed tasks
-
-Creation or population of `tinyTasks.md` does NOT authorize work.
+* Create it and populate it with a proposed task list via `task_add` (or standard file tools if MCP is unavailable)
+* Optionally ask the user to verify the proposed tasks before proceeding
+* If the user requests verification, wait for review
+* If the user declines or does not respond, proceed immediately
 
 Planning in the response body is prohibited once this rule triggers.
 
 #### Task Proposal Allowance
 
-The agent MAY populate `tinyTasks.md` with a proposed task list.
-
-Proposed tasks are NOT authorized until a human:
-- confirms them explicitly, or
-- edits or reorders them, or
-- states approval in plain language
-
-The agent MUST stop after proposing tasks and wait for human authorization.
+The agent MAY populate `tinyTasks.md` with a proposed task list and ask the
+user to verify before proceeding.  Verification is optional — the agent must
+not block waiting for a response that may not come.
 
 ---
 
@@ -201,16 +194,17 @@ Never guess. Never proceed optimistically.
 
 ## 6. tinyTasks.md Templates
 
-### Inert Auto-Creation Template
+### Auto-Creation Template
+
+The agent creates and populates this file in one step.  If verification was
+requested, the file appears with proposed tasks and the agent waits.  Otherwise
+the agent proceeds immediately.
 
 ```md
-# Tasks — PROPOSED
->
-> These tasks were proposed by the agent.
-> No work is authorised until a human reviews and confirms them.
->
-## Tasks
-<!-- No tasks defined yet -->
+# Tasks — <Goal>
+
+- [ ] First task
+- [ ] Second task
 ```
 
 ### Active Task Structure

QWEN.md

@@ -2,11 +2,10 @@
 You operate under TinyMem governance.
 
 If a request would change files, tasks, or memory:
-- use TinyMem MCP tools
+- use TinyMem MCP tools when available; otherwise use standard file tools
 - do not assume state
 - do not claim changes unless a tool call succeeds
 
-Tool calls are the only way to affect reality.
 If a tool call is blocked or rejected, adapt and retry.
 Otherwise, respond normally.
 **End of tinyMem Protocol**

docs/MCP_RESOURCES.md

@@ -1,48 +1,60 @@
-# Ensuring `list_mcp_resources` finds tinyMem
+# Exposing tinyMem MCP tools to Codex
 
-The `list_mcp_resources` lookup that the Codex agent runs before mutating a repository pulls from the shared automation registry (`$CODEX_HOME/automations/*`). In this workspace we only ship the tinyMem code itself, so the registry is empty and the agent cannot find the MCP tool that knows how to validate mutations.
+Codex discovers MCP servers from config files — there is no separate automation
+registry or resource-listing step.  Two scopes are supported:
 
-To keep agents honest when they act in this repo, add a tinyMem automation definition that registers the `tinymem mcp` server (and any helper commands) so `list_mcp_resources` returns a non-empty list.
+| File | Scope |
+|---|---|
+| `~/.codex/config.toml` | global (all projects) |
+| `.codex/config.toml` | project-scoped (can be checked into the repo) |
 
-## How to register tinyMem in the automation registry
+## Adding tinymem to the config
 
-1. Locate your Codex automation directory. By default it’s `$CODEX_HOME/automations/`; if that directory does not exist yet, create it.
-2. Inside `automations/`, add a folder for this repo (for example, `tinymem`). Place a `automation.toml` file there.
-3. Populate `automation.toml` with metadata that exposes the MCP entry point. A minimal example:
+Add the following block to whichever config file applies:
 
-   ```toml
-   title = "tinyMem MCP"
-   description = "Exposes the tinyMem MCP server and diagnostics helpers for repository work."
+```toml
+[mcp_servers.tinymem]
+command = "tinymem"
+args = ["mcp"]
+enabled = true
+startup_timeout_sec = 15
+```
 
-   [server]
-   command = "tinymem"
-   args = ["mcp"]
-   timeout = 60000
-   trust = false
+That is the complete entry.  Codex starts the server on session launch and
+exposes every tool the server advertises (`memory_query`, `memory_recent`,
+`memory_write`, `task_add`, `artifact_create`, etc.) alongside its built-in
+tools.
 
-   [[tools]]
-   name = "tinyMem health"
-   description = "Verify the database before editing."
-   command = "tinymem"
-   args = ["health"]
-   timeout = 15000
+## Project-scoped setup (recommended for this repo)
 
-   [[tools]]
-   name = "tinyMem doctor"
-   description = "Run the doctor diagnostic from MCP context."
-   command = "tinymem"
-   args = ["doctor"]
-   timeout = 30000
-   ```
+Check a `.codex/config.toml` into the repo root with the block above.  Any
+Codex session opened inside the repo will pick it up automatically — no
+per-machine global config needed.
 
-   Adjust the snippet as needed for your environment; the registry that backs `list_mcp_resources` may support additional fields such as `env`, `cwd`, or `trust`.
+## CLI alternative
 
-4. After the automation file is saved, restart the Codex agent (if necessary) so it notices the new resource. Running `list_mcp_resources` again should now show your tinyMem MCP server and any helper tools.
+If you prefer not to hand-edit the file:
 
-## Why this matters
+```bash
+codex mcp add tinymem -- tinymem mcp
+```
 
-- The root `docs/agents/AGENTS.md` contract mandates that repository mutations happen via the MCP tools; registering `tinymem` here keeps codex obeying that contract.
-- Once `list_mcp_resources` returns our entry, we can use the MCP server to call `memory_query`, `memory_recent`, `memory_write`, etc., without manually editing `tinyTasks.md`.
-- The automation can bundle other useful wrappers (`health`, `doctor`, `query`) so agents have quick diagnostics at hand before mutating files.
+This appends the equivalent entry to `~/.codex/config.toml`.
 
-If you need a hand generating the TOML for your automation tool, look for other Codex automation directories on this machine (e.g., `~/.codex/automations/`) for examples, or copy the snippet above and adjust the tool metadata to match.
+## Filtering tools (optional)
+
+If you only want a subset of the tools exposed, use `enabled_tools`:
+
+```toml
+[mcp_servers.tinymem]
+command = "tinymem"
+args = ["mcp"]
+enabled = true
+enabled_tools = ["memory_query", "memory_recent", "memory_write", "task_add"]
+```
+
+## Why the tools weren't showing up
+
+The server was already running, but no config entry existed — Codex had no
+way to know about it.  Once the config block above is in place, the tools
+appear in the next session without any restart.

docs/agents/AGENTS.md

@@ -1,27 +1,26 @@
 **Start of tinyMem Protocol**
-You operate under TinyMem governance.
+You operate under TinyMem governance. This protocol is MANDATORY.
 
-If a request would create files, change files, tasks, or memory:
-- use TinyMem MCP tools when available; otherwise use standard file tools
-- do not assume state
-- do not claim changes unless a tool call succeeds
+### 1. The Workflow
+1. **Observe:** Call `memory_query` or `memory_recent` before any mutation to avoid duplicates or conflict.
+2. **Sequence:** If a task has 2+ steps, externalize them to `tinyTasks.md` (use `task_add`).
+3. **Mutate:** Use standard tools to edit files. Never assume state.
+4. **Persist:** Call `memory_write` immediately after a successful mutation. **NEVER** claim a change until this tool succeeds.
 
-If a tool call is blocked or rejected, adapt and retry.
-Otherwise, respond normally.
+### 2. Guardrails
+- **Fail Closed:** If a tool fails or state is ambiguous, STOP and ask the user.
+- **Tool Authority:** Prefer MCP tools (`memory_*`) over CLI commands when available.
+- **Evidence:** Facts require evidence; decisions require rationale.
 
-**TinyMem tool reference**
-- `tinymem health` — verify the database, schema, and connectivity before any mutation.
-- `tinymem doctor` — run a deeper diagnostic that reports configuration or health issues with storage, recall, or authorities.
-- `tinymem stats` — check current memory/task counts and pass/fail rates to decide whether to update or run additional tooling.
-- `tinymem dashboard` — view or refresh the visual task/memory status when you need awareness of progress or blockers.
-- `tinymem query "<term>"` — search the existing memory store for a term that might affect your next edit.
-- `tinymem recent` — fetch the latest entries so you can reference what tinyMem just learned.
-- `tinymem write --type <type>` — persist a decision, note, or claim once you have collated the facts.
-- `tinymem mcp` — start the stdio server that accepts the `memory_*` tool calls described below.
+### 3. Tool Reference (MCP)
+- `memory_query`: Search contextual memory. **Required** before mutations.
+- `memory_recent`: Fetch latest entries for immediate context.
+- `memory_write`: Persist facts/decisions. **Required** after mutations.
+- `task_add`: Add/Update `tinyTasks.md` entries. **Required** for multi-step work.
 
-- `memory_query` — search contextual memory; required before mutations only in GUARDED/STRICT modes. In PASSIVE mode, mutations proceed without prior recall.
-- `memory_recent` — fetch the most recent memories if you need to reference immediately preceding work.
-- `memory_write` — persist a fact/decision/note; never claim a repository change without this tool concluding successfully.
-- `task_add` — create tinyTasks.md if missing and append a task in one call; use this instead of creating the file manually.
+### 4. Tool Reference (CLI)
+- `tinymem health/doctor`: Verify DB/Config before starting work.
+- `tinymem stats/dashboard`: Check progress and health metrics.
+- `tinymem write/query/recent`: CLI equivalents of MCP tools.
 
-**End of tinyMem Protocol**
+**End of tinyMem Protocol**

docs/agents/AGENT_CONTRACT.md

@@ -1,27 +1,26 @@
 **Start of tinyMem Protocol**
-You operate under TinyMem governance.
+You operate under TinyMem governance. This protocol is MANDATORY.
 
-If a request would create files, change files, tasks, or memory:
-- use TinyMem MCP tools when available; otherwise use standard file tools
-- do not assume state
-- do not claim changes unless a tool call succeeds
+### 1. The Workflow
+1. **Observe:** Call `memory_query` or `memory_recent` before any mutation to avoid duplicates or conflict.
+2. **Sequence:** If a task has 2+ steps, externalize them to `tinyTasks.md` (use `task_add`).
+3. **Mutate:** Use standard tools to edit files. Never assume state.
+4. **Persist:** Call `memory_write` immediately after a successful mutation. **NEVER** claim a change until this tool succeeds.
 
-If a tool call is blocked or rejected, adapt and retry.
-Otherwise, respond normally.
+### 2. Guardrails
+- **Fail Closed:** If a tool fails or state is ambiguous, STOP and ask the user.
+- **Tool Authority:** Prefer MCP tools (`memory_*`) over CLI commands when available.
+- **Evidence:** Facts require evidence; decisions require rationale.
 
-**TinyMem tool reference**
-- `tinymem health` — verify the database, schema, and connectivity before any mutation.
-- `tinymem doctor` — run a deeper diagnostic that reports configuration or health issues with storage, recall, or authorities.
-- `tinymem stats` — check current memory/task counts and pass/fail rates to decide whether to update or run additional tooling.
-- `tinymem dashboard` — view or refresh the visual task/memory status when you need awareness of progress or blockers.
-- `tinymem query "<term>"` — search the existing memory store for a term that might affect your next edit.
-- `tinymem recent` — fetch the latest entries so you can reference what tinyMem just learned.
-- `tinymem write --type <type>` — persist a decision, note, or claim once you have collated the facts.
-- `tinymem mcp` — start the stdio server that accepts the `memory_*` tool calls described below.
+### 3. Tool Reference (MCP)
+- `memory_query`: Search contextual memory. **Required** before mutations.
+- `memory_recent`: Fetch latest entries for immediate context.
+- `memory_write`: Persist facts/decisions. **Required** after mutations.
+- `task_add`: Add/Update `tinyTasks.md` entries. **Required** for multi-step work.
 
-- `memory_query` — search contextual memory; required before mutations only in GUARDED/STRICT modes. In PASSIVE mode, mutations proceed without prior recall.
-- `memory_recent` — fetch the most recent memories if you need to reference immediately preceding work.
-- `memory_write` — persist a fact/decision/note; never claim a repository change without this tool concluding successfully.
-- `task_add` — create tinyTasks.md if missing and append a task in one call; use this instead of creating the file manually.
+### 4. Tool Reference (CLI)
+- `tinymem health/doctor`: Verify DB/Config before starting work.
+- `tinymem stats/dashboard`: Check progress and health metrics.
+- `tinymem write/query/recent`: CLI equivalents of MCP tools.
 
-**End of tinyMem Protocol**
+**End of tinyMem Protocol**

docs/agents/AGENT_CONTRACT_SMALL.md

@@ -1,27 +1,26 @@
 **Start of tinyMem Protocol**
-You operate under TinyMem governance.
+You operate under TinyMem governance. This protocol is MANDATORY.
 
-If a request would create files, change files, tasks, or memory:
-- use TinyMem MCP tools when available; otherwise use standard file tools
-- do not assume state
-- do not claim changes unless a tool call succeeds
+### 1. The Workflow
+1. **Observe:** Call `memory_query` or `memory_recent` before any mutation to avoid duplicates or conflict.
+2. **Sequence:** If a task has 2+ steps, externalize them to `tinyTasks.md` (use `task_add`).
+3. **Mutate:** Use standard tools to edit files. Never assume state.
+4. **Persist:** Call `memory_write` immediately after a successful mutation. **NEVER** claim a change until this tool succeeds.
 
-If a tool call is blocked or rejected, adapt and retry.
-Otherwise, respond normally.
+### 2. Guardrails
+- **Fail Closed:** If a tool fails or state is ambiguous, STOP and ask the user.
+- **Tool Authority:** Prefer MCP tools (`memory_*`) over CLI commands when available.
+- **Evidence:** Facts require evidence; decisions require rationale.
 
-**TinyMem tool reference**
-- `tinymem health` — verify the database, schema, and connectivity before any mutation.
-- `tinymem doctor` — run a deeper diagnostic that reports configuration or health issues with storage, recall, or authorities.
-- `tinymem stats` — check current memory/task counts and pass/fail rates to decide whether to update or run additional tooling.
-- `tinymem dashboard` — view or refresh the visual task/memory status when you need awareness of progress or blockers.
-- `tinymem query "<term>"` — search the existing memory store for a term that might affect your next edit.
-- `tinymem recent` — fetch the latest entries so you can reference what tinyMem just learned.
-- `tinymem write --type <type>` — persist a decision, note, or claim once you have collated the facts.
-- `tinymem mcp` — start the stdio server that accepts the `memory_*` tool calls described below.
+### 3. Tool Reference (MCP)
+- `memory_query`: Search contextual memory. **Required** before mutations.
+- `memory_recent`: Fetch latest entries for immediate context.
+- `memory_write`: Persist facts/decisions. **Required** after mutations.
+- `task_add`: Add/Update `tinyTasks.md` entries. **Required** for multi-step work.
 
-- `memory_query` — search contextual memory; required before mutations only in GUARDED/STRICT modes. In PASSIVE mode, mutations proceed without prior recall.
-- `memory_recent` — fetch the most recent memories if you need to reference immediately preceding work.
-- `memory_write` — persist a fact/decision/note; never claim a repository change without this tool concluding successfully.
-- `task_add` — create tinyTasks.md if missing and append a task in one call; use this instead of creating the file manually.
+### 4. Tool Reference (CLI)
+- `tinymem health/doctor`: Verify DB/Config before starting work.
+- `tinymem stats/dashboard`: Check progress and health metrics.
+- `tinymem write/query/recent`: CLI equivalents of MCP tools.
 
-**End of tinyMem Protocol**
+**End of tinyMem Protocol**