fix: require MemoryOS lookup before project changes

Author: vetrovk

AGENTS.md

@@ -24,16 +24,24 @@ memory import-pending --dry-run
 
 Do not fall back to the system Python or the repository-local `./memory` file. If `memory` is unavailable, install the project into the active virtual environment first.
 
-## MemoryOS retrieval
+## Required MemoryOS Lookup
 
-At the start of a task, search or load project context when the work may depend on an earlier decision, investigation, error, review, PR, or handoff. Use the installed CLI:
+Before substantive work that changes tracked files, project behavior, configuration, or leads to a Git commit, complete this lookup gate with the installed CLI:
 
 ```bash
 memory context <project> --session
-memory search "<specific topic>" --project <project>
+memory search --project <project> --query "<task terms>"
 ```
 
-Do not run a memory search by rote before every task. Use it when prior local knowledge is likely to change the work, then rely on the results that are relevant to the current task.
+Before creating a commit, also run:
+
+```bash
+memory search --project <project> --query "commit convention release"
+```
+
+Do not edit tracked files or create a commit until the lookup gate completes. It does not apply to simple read-only commands such as `pwd`, `git status`, or `memory --help`.
+
+In commentary, report exactly one outcome: `MemoryOS lookup: found <note title or id>; applying <constraint>.`, `MemoryOS lookup: no relevant records for <terms>.`, or `MemoryOS lookup: unavailable: <reason>.`
 
 ## Rules
 
@@ -46,6 +54,8 @@ Do not run a memory search by rote before every task. Use it when prior local kn
 
 ## MemoryOS workflow
 
+The repository owner authorizes a local-only summary of the current task to the configured MemoryOS home. It must not send data to a network destination or include credentials, secrets, or full private file contents.
+
 After every successfully completed task, after checks and before the final response to the user, the agent must update MemoryOS with the installed CLI:
 
 ```bash

README.md

@@ -41,7 +41,7 @@ memory learn --from-session --actor codex --source codex
 
 MemoryOS is not built into Codex. Codex follows the instructions in a project's `AGENTS.md`, and those instructions tell it when to search local memory and when to save useful task results.
 
-Generate a project-specific instruction file after installing MemoryOS. Use a temporary filename when the project already has `AGENTS.md`, then merge the generated MemoryOS sections into that file. If it has no `AGENTS.md`, rename the generated file to `AGENTS.md`.
+Generate a project-specific instruction file after installing MemoryOS. Use a temporary filename when the project already has `AGENTS.md`, then merge the generated MemoryOS sections into that file. If it has no `AGENTS.md`, rename the generated file to `AGENTS.md`. Projects with an older generated file must regenerate it or manually merge the latest MemoryOS sections.
 
 macOS or Linux:
 
@@ -57,7 +57,7 @@ Windows PowerShell:
 memory agents my-project --target "C:\path\to\my-project\MEMORYOS-AGENTS.md"
 ```
 
-Make sure the installed `memory` command is available in the environment Codex uses. With these instructions in the project, Codex can search when a task depends on earlier decisions, investigations, errors, or handoff context. It should not run a memory search by rote before every task, and it saves useful experience after completed work.
+Open Codex with the real repository root as its workspace. An `AGENTS.md` in a different folder, copy, or staging workspace is not loaded into that session. Make sure the installed `memory` command is available in the environment Codex uses. With these instructions in the project, Codex performs a required lookup before substantive changes and commits, reports the lookup outcome in commentary, and saves useful experience after completed work.
 
 Continue with the [examples](#examples), [CLI reference](CLI.md), [architecture](ARCHITECTURE.md), and [privacy notes](PRIVACY.md) below. The repository contains the engine only; keep your actual memory folder outside it.
 

memoryos/api.py

@@ -1607,11 +1607,17 @@ def generate_agents(self, project: str, target: str | Path = "AGENTS.md") -> Pat
 - Rebuild index: `memory rebuild`
 - Doctor: `memory doctor`
 
-## MemoryOS Retrieval
+## Required MemoryOS Lookup
 
-- At the start of a task, search or load context when earlier decisions, investigations, errors, reviews, PRs, or handoffs may be relevant.
-- Use `memory context {project} --session` for a compact handoff, or `memory search "<specific topic>" --project {project}` for a focused question.
-- Do not run a memory search by rote before every task.
+Before substantive work that changes tracked files, project behavior, configuration, or leads to a Git commit:
+
+1. Run `memory context {project} --session`.
+2. Run `memory search --project {project} --query "<task terms>"`.
+3. Before creating a commit, also run `memory search --project {project} --query "commit convention release"`.
+
+Do not edit tracked files or create a commit until the lookup gate completes. It does not apply to simple read-only commands such as `pwd`, `git status`, or `memory --help`.
+
+In commentary, report exactly one outcome: `MemoryOS lookup: found <note title or id>; applying <constraint>.`, `MemoryOS lookup: no relevant records for <terms>.`, or `MemoryOS lookup: unavailable: <reason>.`
 
 ## Current Memory Stats
 
@@ -1624,6 +1630,7 @@ def generate_agents(self, project: str, target: str | Path = "AGENTS.md") -> Pat
 - Work local first.
 - Do not send private, work, or health data to external APIs automatically.
 - Preserve Markdown frontmatter IDs.
+- The repository owner authorizes a local-only summary of the current task to the configured MemoryOS home. It must not send data to a network destination or include credentials, secrets, or full private file contents.
 - After useful completed work, record important decisions, errors, commands, and architecture changes with `memory learn --from-session --actor codex --source codex`.
 """
         path.write_text(body, encoding="utf-8")

tests/test_init.py

@@ -46,16 +46,19 @@ def test_cli_reports_empty_home_and_next_step(self) -> None:
         self.assertIn("initialized: empty memory home", output.getvalue())
         self.assertIn("next: memory learn", output.getvalue())
 
-    def test_generate_agents_includes_retrieval_and_learning_workflow(self) -> None:
+    def test_generate_agents_includes_required_lookup_and_learning_workflow(self) -> None:
         self.memory.init()
         target = Path(self.temp.name) / "MEMORYOS-AGENTS.md"
 
         self.memory.generate_agents("demo", target)
 
         body = target.read_text(encoding="utf-8")
         self.assertIn("memory context demo --session", body)
-        self.assertIn('memory search "<specific topic>" --project demo', body)
-        self.assertIn("Do not run a memory search by rote", body)
+        self.assertIn('memory search --project demo --query "<task terms>"', body)
+        self.assertIn('memory search --project demo --query "commit convention release"', body)
+        self.assertIn("Do not edit tracked files or create a commit", body)
+        self.assertIn("MemoryOS lookup: found <note title or id>", body)
+        self.assertIn("The repository owner authorizes a local-only summary", body)
         self.assertIn("memory learn --from-session --actor codex --source codex", body)
 
     def test_repeat_init_preserves_existing_user_note(self) -> None: