sae4u-memory 0.2.0__py3-none-any.whl

sae4u_memory/__init__.py

@@ -0,0 +1,3 @@
+"""SAE4U Memory — persistent memory architecture for Claude."""
+
+__version__ = "0.2.0"

sae4u_memory/_assets/commands/memory-distill.md

@@ -0,0 +1,71 @@
+# /memory-distill — weekly memory cleanup
+
+A periodic ritual: read the rolling tick log, propose promotions to
+permanent memory, and let the user confirm what to keep, archive,
+or forget.
+
+## When to run
+
+- Weekly (e.g. Sunday evening or Monday morning).
+- After heavy context-creation periods (a sprint close, a launch).
+- When tick log files have piled up beyond what a quick scan can
+  digest (~5+ days of unmerged ticks).
+
+## What it does
+
+1. **Read the tick logs** — all files under `~/.sae4u-memory/tick/`
+   that haven't been distilled yet, plus any new permanent files
+   added since last distill.
+2. **Cluster** by topic (use the 4 types — user/feedback/project/
+   reference — as a first cut, then group within type by topic).
+3. **Propose actions** for each cluster. Three outcomes per item:
+   - **Promote** to a permanent file (new or merge into existing).
+     Update MEMORY.md.
+   - **Drop** — was tick-only noise; not worth keeping.
+   - **Keep in tick log** — borderline; see again next week.
+4. **Surface for confirmation.** The user reviews the proposals
+   and accepts / rejects each. Never auto-promote, never
+   auto-forget — see `rules/memory-cleanup-interactive.md`.
+5. **Apply** the confirmed actions:
+   - Move tick entries to permanent files
+   - Update MEMORY.md index
+   - Archive distilled tick log file (e.g. rename to
+     `tick/distilled/2026-05-07.md` or compress)
+6. **Stale check** for permanent memory — entries not referenced
+   in N weeks. Ask: "still interesting or forget?" Don't volunteer
+   to delete; just surface the question.
+
+## How the AI presents this
+
+Group by topic, not by file. The user shouldn't have to read 40
+individual proposals — bundle related ticks into "here are 5 things
+about X, what shape do you want them in?"
+
+Keep the proposals concrete:
+
+> ### Topic: testing approach
+>
+> Across 4 ticks last week:
+> - 2026-05-02 — "don't mock the database in integration tests"
+> - 2026-05-04 — confirmed "TDD for new API endpoints"
+> - 2026-05-05 — "use testcontainers for postgres in CI"
+> - 2026-05-06 — "snapshot tests OK for component output"
+>
+> Propose: promote to `feedback_testing_approach.md` consolidating
+> all four. Drop the per-tick entries from tick log.
+>
+> Accept / Reject?
+
+## Implementation
+
+This is a slash-command spec (Claude Code), not an automated job.
+The AI reads it as guidance and runs through the steps interactively.
+
+You can wire it into a routine:
+
+```bash
+# Weekly cron — reminds you to run distill in next session
+0 18 * * SUN echo "/memory-distill" | tee -a ~/.sae4u-memory/distill-due.log
+```
+
+Or just rely on calendar / habit.

sae4u_memory/_assets/docs/architecture.md

@@ -0,0 +1,107 @@
+# Architecture
+
+`sae4u-memory` is built around five concepts:
+
+1. **Two-corpus recall** — semantic-ish search over SQLite facts
+   (written via `remember`) AND markdown files in your auto-memory
+   dirs and `~/.sae4u-memory/`.
+2. **MEMORY.md as the index** — a single table of contents pointing
+   to per-topic files. Loaded into context at session start.
+3. **4-type classification** — every memory is one of `user`,
+   `feedback`, `project`, or `reference`. Each type has different
+   handling and shelf life.
+4. **Tick / permanent split** — borderline observations go to a
+   day-rolling tick log (NOT indexed in MEMORY.md). Foundational
+   items go directly to permanent files indexed in MEMORY.md.
+5. **Persona at session start** — `get_persona()` returns a
+   working-rules document plus user context, loaded fresh.
+
+## File layout
+
+```
+~/.sae4u-memory/
+├── memory.db               # SQLite facts written via remember()
+├── persona.md              # AI's identity + rules (edit to customize)
+├── MEMORY.md               # Index of permanent files (loaded at session start)
+├── user/                   # User context loaded by get_persona()
+│   ├── identity.md
+│   ├── projects.md
+│   └── preferences.md
+├── tick/                   # Day-rolling tick log
+│   └── 2026-05-07.md
+├── archive/                # User-confirmed archived files (optional)
+├── journals/               # End-of-session narratives
+│   └── 2026-05-07.md
+└── .last_tick              # Epoch timestamp of last memory tick
+```
+
+In Claude Code, the additional auto-memory dir lives at
+`~/.claude/projects/<project-slug>/memory/` — `recall()` searches
+that too, by default.
+
+## The 4 types
+
+### `user`
+Facts about who the user is — role, goals, knowledge, responsibilities,
+preferences. Helps tailor future behavior. Does NOT decay quickly.
+
+> Example: "Senior backend engineer, 10 years Go, new to React.
+> Prefers explanation in terms of backend analogues."
+
+### `feedback`
+Corrections AND validations. Every time the user pushes back ("don't
+do X") OR confirms a non-obvious approach worked ("yes exactly,
+keep doing that"). Lead with the rule, then **Why:** and
+**How to apply:** lines.
+
+> Example: see `rules/no-hardcode.md`
+
+### `project`
+Ongoing work, decisions, motivations, deadlines. **Decays fast** —
+convert relative dates to absolute ones at write time
+("Thursday" → "2026-03-05"). Re-evaluate periodically.
+
+> Example: "Merge freeze begins 2026-03-05 for mobile release.
+> Flag any non-critical PR scheduled after."
+
+### `reference`
+Pointers to external systems where information lives. Slack channels,
+ticket queues, dashboards, documentation portals. Tells the AI where
+to look — does not duplicate the content.
+
+> Example: "Bugs tracked in Linear project INGEST. Check there for
+> pipeline issues."
+
+## What NOT to save
+
+- Code patterns, conventions, file paths, project structure — these
+  can be re-derived from reading the current state.
+- Git history or recent changes — `git log` / `git blame` are
+  authoritative.
+- Debugging recipes — the fix is in the code; the commit message
+  has the context.
+- Anything already documented in CLAUDE.md.
+- Ephemeral task state — that's what the conversation is for.
+
+These exclusions apply even when the user explicitly asks. If they
+ask for an "activity summary", ask what was *surprising* — that's
+the part worth keeping.
+
+## How recall works
+
+`recall(query)` returns a merged stream from two sources:
+
+1. **SQLite (FTS5):** facts written with `remember(text, category)`.
+   Indexed by full-text search. Good for "recall what I told you about X".
+2. **Markdown:** files under `~/.sae4u-memory/` and Claude Code
+   auto-memory dirs. Ranked by weighted keyword scoring with a
+   recency bonus for tick logs. Good for "what's the rule about Y"
+   and "what did I write down recently".
+
+Filter sources via `sources="sqlite"` or `sources="markdown"` if you
+want only one corpus.
+
+## Cleanup
+
+Don't auto-forget. Use `/memory-distill` (see `commands/memory-distill.md`)
+periodically. The user has agency over what gets archived or deleted.

sae4u_memory/_assets/docs/episodic-bridge.md

@@ -0,0 +1,118 @@
+# Optional: episodic bridge for remote dev boxes
+
+If your work spans more than one machine — e.g. you have a remote
+build server, a production droplet, or a dedicated dev box —
+`sae4u-memory` semantic memory (markdown + SQLite) only knows what
+you told it from your local machine. Episodic state on the remote
+box (last cron run, last deploy, last service health check, last
+backlog edit) is invisible to it.
+
+This doc describes a pattern for bridging that gap **without**
+sending PII or session state through the AI's semantic memory.
+
+## The pattern
+
+On the remote machine, maintain three things:
+
+1. **A backlog file** — single source of truth for open work,
+   updated by you (or your tooling) as items move.
+2. **A session-open script** — emits a digest: services running,
+   memory/disk state, last activity timestamps, top P0 items.
+3. **A previous-session-backup directory** — at the end of each
+   session, your session-close prompt drops a context-transfer
+   note in there, dated.
+
+At session open, run the script and `cat` the backup. Feed the
+output to the AI. Now the AI has actual artifacts (not vibes) to
+ground "what changed since last time" answers.
+
+## Suggested layout (on the remote box)
+
+```
+/path/to/your/state/
+├── BACKLOG.md
+├── scripts/
+│   └── session_open.sh         # emits the digest
+├── previous_session_backup/
+│   └── context_transfer_2026-05-07.md
+└── session-log.md              # optional: chronological log
+```
+
+## Suggested session-open script (template)
+
+```bash
+#!/usr/bin/env bash
+# session_open.sh — emits session digest for the AI to ingest at start.
+set -e
+
+cat <<HEADER
+=================================================================
+SESSION OPEN — $(date '+%Y-%m-%d %H:%M %Z')
+=================================================================
+
+SERVICES
+HEADER
+
+# Replace with your actual checks
+systemctl status myapp | head -3 || true
+
+cat <<DIVIDER
+
+SYSTEM
+  Memory: $(free -h | awk '/^Mem:/ {print $3 "/" $2}')
+  Disk:   $(df -h / | awk 'NR==2 {print $5 " (" $3 "/" $2 ")"}')
+
+LAST SESSION
+DIVIDER
+
+ls -1t previous_session_backup/context_transfer_*.md 2>/dev/null \
+    | head -1 | xargs -I {} head -10 {}
+
+echo
+echo "P0 BACKLOG"
+grep -E '^\s*-\s*\[ \].*\*\*BL-' BACKLOG.md 2>/dev/null | head -5
+
+cat <<FOOTER
+
+=================================================================
+Ready.
+=================================================================
+FOOTER
+```
+
+## At session open
+
+In Claude Code, your session-open prompt invokes the script:
+
+```
+ssh <remote-host> '/path/to/your/state/scripts/session_open.sh'
+ssh <remote-host> 'cat /path/to/your/state/BACKLOG.md'
+
+Read the latest context_transfer in previous_session_backup/.
+
+Then mirror the prior handoff card 1:1 (per
+rules/session-open-mirror-handoff.md), then add your suggestions
+in a separate marked block.
+```
+
+## At session close
+
+Drop a context-transfer note for next time:
+
+```
+ssh <remote-host> 'cp /path/to/your/state/context_transfer_$(date +%F).md \
+    /path/to/your/state/previous_session_backup/'
+```
+
+## What to keep in semantic memory vs episodic bridge
+
+- **Semantic memory** (markdown + SQLite): identity, decisions,
+  rules, project facts, preferences. Stable across sessions.
+- **Episodic bridge** (remote artifacts): session state, current
+  service health, last touched file, today's commits, this week's
+  backlog churn. Volatile, refreshed per session.
+
+Don't let episodic state leak into semantic memory. If it's
+"yesterday I deployed X", that goes in a context-transfer note,
+not in MEMORY.md. Permanent memory is for things that will still
+be true in three weeks.

sae4u_memory/_assets/docs/persona-customization.md

@@ -0,0 +1,77 @@
+# Persona customization
+
+The default persona ships as **Simple** — a peer-level coder friend
+with persistent memory. It's deliberately generic. Edit
+`~/.sae4u-memory/persona.md` to make it yours.
+
+## What's editable
+
+The full persona document. The default is a working-rules style with:
+
+- Identity (name = Simple, role = peer-level dev pal)
+- Core values (Honesty > Comfort, Shipped > Perfect, etc.)
+- Voice (terse, direct, match user register)
+- Never do / Always do lists
+- Memory discipline (which tools to call when)
+- Memory architecture awareness (4 types)
+
+You can rewrite any of these. Common customizations:
+
+- **Change the name** — "Simple" is the default. Keep it, or rename.
+- **Add domain context** — what stack you work in, what languages,
+  what products you build, what your role is.
+- **Add behavior modes** — "in code review mode, do X. In
+  brainstorm mode, do Y." Modes can be mood-triggered ("when I
+  swear or panic, switch to crisis mode").
+- **Adjust the language default** — match your primary language.
+  The default works in English; the rules are language-agnostic.
+- **Adjust verbosity** — the default leans terse. If you want more
+  explanation, say so explicitly.
+
+## What's loaded at session start
+
+`get_persona()` returns:
+
+1. The full content of `~/.sae4u-memory/persona.md`.
+2. All `*.md` files under `~/.sae4u-memory/user/`, in alphabetical
+   order, concatenated as "User Context".
+
+So you can split things logically:
+
+```
+~/.sae4u-memory/
+├── persona.md              # behavior rules
+└── user/
+    ├── identity.md         # who you are
+    ├── projects.md         # what you work on
+    ├── preferences.md      # how you like to collaborate
+    └── stack.md            # what tech you use
+```
+
+`get_persona()` returns all of it as one block. Order matters
+(alphabetical) — name files accordingly.
+
+## What NOT to put in persona
+
+- Live project state — use `remember()` and `recall()` for that.
+- Per-task instructions — those belong in the prompt, not persona.
+- Sensitive secrets — persona is plaintext on disk. Don't put API
+  keys there.
+- Long histories — persona is loaded every session, so it costs
+  tokens. Keep it tight; push history to per-topic memory files.
+
+## Example: adding domain context
+
+```markdown
+## Stack
+
+- Backend: Python 3.12, FastAPI, PostgreSQL, Redis
+- Frontend: React + TypeScript, Tailwind
+- Infra: AWS (ECS), GitHub Actions, Terraform
+- Editor: Cursor
+
+When I ask for code, default to these unless I say otherwise.
+```
+
+Add this to `~/.sae4u-memory/user/stack.md` and `get_persona()` will
+load it automatically next session.

sae4u_memory/_assets/docs/tick-protocol.md

@@ -0,0 +1,86 @@
+# Tick protocol
+
+`hooks/memory-tick.sh` is a Claude Code `UserPromptSubmit` hook that
+fires every 10 minutes (configurable). It does NOT write memory itself —
+it injects a system reminder telling the AI to do a brief review.
+
+## Why
+
+Reactive-only memory writes leave gaps. The AI may judge something
+unimportant in the moment that turns out to matter later. The tick
+gives a forced moment to capture borderline observations before they
+fall out of conversation context.
+
+## What happens at a tick
+
+1. The hook calculates how long since the last tick (stored in
+   `~/.sae4u-memory/.last_tick`).
+2. If the elapsed time is below the interval (default 600s), the
+   hook exits silently — no extra context, no impact.
+3. Otherwise, the hook returns a JSON `hookSpecificOutput` whose
+   `additionalContext` field contains an instruction.
+4. The AI receives that instruction along with the user's prompt
+   and silently:
+   - Reviews the last ~10 min of conversation
+   - Classifies new facts/decisions/preferences into 4 types
+   - Appends to the day's tick log
+     (`~/.sae4u-memory/tick/YYYY-MM-DD.md`)
+   - For foundational items (architecture, strategy, naming,
+     identity, or items the user explicitly flagged), writes
+     directly to permanent memory and updates MEMORY.md
+   - Updates `~/.sae4u-memory/.last_tick`
+5. THEN the AI answers the user normally. The tick is silent —
+   the user doesn't see it.
+
+## Tick log entry format
+
+```markdown
+## HH:MM — [type] short title
+
+Body. One paragraph is enough. Pointer to permanent file if this
+got promoted.
+```
+
+Tick log files are NOT indexed in MEMORY.md. They're sorted through
+periodically by `/memory-distill` (see `commands/memory-distill.md`).
+
+## When tick writes to permanent memory directly
+
+Three cases:
+
+1. **User explicit signal** — they said "remember this for the long
+   term", "this is important", "in soul" or similar.
+2. **Foundational decision** — architecture, strategy, naming, core
+   identity, anything that changes how future work is framed.
+3. **Supersedes existing permanent memory** — the new fact contradicts
+   or refines an existing permanent file.
+
+In all three cases, add `critical: true` to the frontmatter if the
+item is foundational.
+
+For everything else: tick log first, distill later.
+
+## Tuning
+
+Configure interval and home dir via environment:
+
+```bash
+# Override tick interval (seconds). Default 600.
+# (Edit hooks/memory-tick.sh to change at hook level.)
+
+# Override memory home. Default ~/.sae4u-memory.
+export SAE4U_MEMORY_HOME=/path/to/your/memory
+```
+
+## Common gotchas
+
+- **Empty ticks are valid.** If nothing meaningful emerged in the
+  10-min window, the AI just updates the timestamp.
+- **The tick is a review, not a write.** The instruction is to
+  consider, classify, and write only if there's substance. Lower
+  the importance threshold so borderline items get into the tick
+  log — they get distilled later.
+- **Don't write a "session log".** Always classify into the 4
+  types. Session-state recap belongs in the context-transfer
+  note (see `prompts/session-close.md`), not in tick logs.
+- **Don't mention the tick to the user.** The protocol is silent.

sae4u_memory/_assets/hooks/memory-tick.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# memory-tick.sh — Claude Code UserPromptSubmit hook for sae4u-memory.
+#
+# Fires on every user prompt. If >= INTERVAL_SECONDS have elapsed since the
+# last tick, injects a system-reminder instructing the AI to silently review
+# the last ~10 minutes of conversation, classify any new facts/decisions/
+# preferences into 4 types, and append to the day's tick log (or, only when
+# explicitly foundational, write directly to permanent memory).
+#
+# This implements the "tick protocol": memory writes happen on a regular
+# rhythm, not only reactively, with a lower importance threshold at tick
+# time so borderline items get captured for later distillation.
+#
+# Always exits 0 so it never blocks user prompts.
+
+set +e
+
+# === CONFIG ============================================================
+
+# Time between forced memory reviews (seconds).
+INTERVAL_SECONDS=600
+
+# Where ~/.sae4u-memory lives. Override with SAE4U_MEMORY_HOME env var.
+MEMORY_DIR="${SAE4U_MEMORY_HOME:-$HOME/.sae4u-memory}"
+
+# Where the timestamp file lives.
+TICK_FILE="${MEMORY_DIR}/.last_tick"
+
+# === LOGIC =============================================================
+
+mkdir -p "$MEMORY_DIR" 2>/dev/null
+mkdir -p "${MEMORY_DIR}/tick" 2>/dev/null
+
+if [[ -f "$TICK_FILE" ]]; then
+    LAST_TICK=$(cat "$TICK_FILE" 2>/dev/null || echo 0)
+else
+    LAST_TICK=0
+fi
+
+if ! [[ "$LAST_TICK" =~ ^[0-9]+$ ]]; then
+    LAST_TICK=0
+fi
+
+NOW=$(date +%s)
+ELAPSED=$((NOW - LAST_TICK))
+
+if (( ELAPSED < INTERVAL_SECONDS )); then
+    exit 0
+fi
+
+MINUTES=$((ELAPSED / 60))
+TODAY=$(date +%Y-%m-%d)
+
+cat <<JSON
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "MEMORY TICK — ${MINUTES} min since last tick.\n\nBEFORE answering the user, do this silently:\n\n1. Review the last ~10 min of conversation.\n2. For each new fact/decision/preference, classify by 4 types (user/feedback/project/reference).\n3. DEFAULT destination: append to tick log ${MEMORY_DIR}/tick/${TODAY}.md. Use format:\n   ## HH:MM — [type] short title\n   Body.\n   If file doesn't exist, create with a single-line header: # Tick log ${TODAY}\n4. EXCEPTION — write DIRECTLY to permanent memory (and update MEMORY.md index) ONLY when:\n   - The user explicitly said it's important / 'remember this for the long term' / 'in soul'\n   - It's a foundational decision (architecture, strategy, naming, core identity)\n   - It corrects/overrides an existing permanent memory file\n   When writing to a permanent file, add 'critical: true' to frontmatter if it's foundational.\n5. LOWER importance threshold in tick log — record borderline items there. The /memory-distill command will sort through them later.\n6. If nothing meaningful emerged, just update the timestamp.\n7. ALWAYS end the tick with: echo \$(date +%s) > ${MEMORY_DIR}/.last_tick\n\nTick log does NOT get indexed in MEMORY.md. Do NOT mention the tick to the user unless asked. Stay silent, then answer the user's prompt."
+  }
+}
+JSON
+
+exit 0

sae4u_memory/_assets/prompts/session-close.md

@@ -0,0 +1,39 @@
+# Session-close prompt
+
+Use this at the end of a working session to capture everything before context evaporates.
+
+```
+Close the session.
+
+0. Describe in detail what we did, where we stopped, and what we
+   decided to start with next session.
+
+1. Update any backlog/tracker:
+   - close items we shipped (with a one-line note explaining what landed)
+   - re-prioritize remaining items if anything shifted
+   - add any new items uncovered today
+
+2. Write today's context-transfer note covering:
+   - Done — what we shipped (with commits/PRs/files)
+   - Decided — non-obvious decisions and their reasons
+   - Issues — blockers, known broken things, tech debt added today
+   - Todo — what's next, in the same shape we'd want to read it back
+
+3. If something foundational changed (architecture, strategy, naming,
+   identity) — update permanent memory and the MEMORY.md index. If a
+   prior permanent memory was superseded, mark the old one or remove
+   from the index.
+
+4. Show the summary: what's done, what's left, P0 for next session.
+
+5. Make a backup of today's context-transfer somewhere durable
+   (e.g. `previous_session_backup/context_transfer_YYYY-MM-DD.md`)
+   so the next session can read it without losing context.
+```
+
+## Optional: end-of-session journal
+
+Call `journal(text)` with a short narrative of the session. The journal
+is human-readable Markdown under `~/.sae4u-memory/journals/YYYY-MM-DD.md`,
+useful for retrospectives. It does not replace the context-transfer file —
+the context-transfer is for the next session, the journal is for you.

sae4u_memory/_assets/prompts/session-open.md

@@ -0,0 +1,45 @@
+# Session-open prompt
+
+Use this at the start of a working session to restore episodic context without confabulating.
+
+```
+Open the session.
+
+1. Pull current project state from real artifacts — not from memory:
+   - `git log --oneline -30` on whatever repo we're working on
+   - `ls -lat` on the working directory(ies) we touched yesterday
+   - any backlog/issue tracker URL or local file (e.g. BACKLOG.md, TODO.md)
+
+2. If there's a previous-session backup or context-transfer note (e.g.
+   `previous_session_backup/context_transfer_YYYY-MM-DD.md`), read it.
+   Episodic memory restored without confabulation.
+
+3. Mirror the prior session's handoff card 1:1 first — same items,
+   same order, same accents, same closing line. Don't drop items even
+   if they look stale; don't reorder; don't add suggestions inside the
+   mirror.
+
+4. THEN, in a separate clearly-marked block ("## My take" or similar),
+   add your own suggestions, forks, and proposals. Mark explicitly as
+   additions.
+
+5. Open questions from the transfer ("Should we do X?") stay as open
+   questions — never promote them to decided options inside the mirror.
+
+Show me: what changed since last session, P0 items, what we do today.
+```
+
+## Why this shape
+
+Without artifacts, "yesterday's work" is the most confabulation-prone class
+of question — see `rules/no-session-state-confabulation.md`.
+
+Without a 1:1 mirror, suggestions silently rewrite yesterday's decisions —
+see `rules/session-open-mirror-handoff.md`.
+
+## Optional: remote dev box
+
+If you keep episodic state on a remote machine (a "session opener" pattern —
+running scripts that emit a digest, with backups under
+`previous_session_backup/`), drop your specific commands in step 1 and 2.
+The defaults above assume a local-only setup.

sae4u_memory/_assets/rules/agents-no-delete-features.md

@@ -0,0 +1,36 @@
+---
+name: Don't delete existing features when refactoring
+description: When refactoring or fixing code, preserve all existing sections and features. Never remove functionality without explicit confirmation. Catalog before, verify after.
+type: feedback
+---
+
+When analyzing, refactoring, or fixing code, the AI must NOT delete
+or remove existing sections, features, or data that was already
+working. If a section needs to be rewritten, the replacement must
+include all the content from the original.
+
+**Why:** Refactor agents often remove sections they don't understand
+the purpose of, assuming dead code or unused features. The result
+is silent data loss that the user only catches later — sometimes
+much later.
+
+A typical anti-pattern: an agent fixing a dashboard generator removes
+the "Keyword Research" and "Seed Keywords" sections from the template
+because they don't see how those sections are populated, not realizing
+those are read by a different cron job that runs later.
+
+**How to apply:**
+
+- **Before modifying any file**, catalog ALL existing sections,
+  functions, features, data fields. List them.
+- **After modification**, verify the same sections exist in the
+  output. Diff against the catalog.
+- If a section can't be preserved due to a needed refactor,
+  flag it explicitly and ask for confirmation BEFORE removing.
+- Never assume a section is "dead" or "unnecessary" — it may be
+  there for a reason that's not visible from this file.
+- This applies to HTML templates, Python generators, config files,
+  CSS, and any production code.
+- For consumed files (cron output, bot input), the consumer's
+  expectations determine what must be preserved — even content
+  that looks like noise from inside the writer's view.

sae4u_memory/_assets/rules/grep-before-asking.md

@@ -0,0 +1,30 @@
+---
+name: Grep / read before asking the user for data
+description: If the data is likely to exist in conversation files, codebase, or memory, search for it before asking the user to provide it. Only ask for truly external data (preferences, future picks).
+type: feedback
+---
+
+Before asking the user to provide a value — API key, URL, ID, price,
+config — **search the codebase, conversation files, and memory first**.
+Half the time it's already there.
+
+**Why:** Asking for data that the user already gave you (or that's
+sitting in a file you read minutes ago) is a trust killer. It signals
+you weren't paying attention. Worse, it makes interactive sessions
+feel like data-entry forms.
+
+**How to apply:**
+
+- Before any user-facing question that requests data, run one
+  grep/find pass on the relevant artifacts:
+  - Repo files (`grep` for the keyword, `find` for filename hints)
+  - Recent conversation context
+  - Memory (`recall(query)` with related terms)
+  - Project trackers (backlog, issues, README)
+- The bar: only ask the user when the data is genuinely external
+  to their working context — a preference they haven't expressed,
+  a strategic pick that depends on future intent, an external system
+  the AI cannot read.
+- Strategic / preference questions (which approach, which target
+  audience) are valid to ask. Lookup questions for data that exists
+  somewhere in the repo are not.