sae4u-memory 0.2.0__tar.gz

sae4u_memory-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simple4u / Very Simple Solutions Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sae4u_memory-0.2.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: sae4u-memory
+Version: 0.2.0
+Summary: Persistent memory architecture for Claude — MCP server + hooks + rules + prompts. Part of the SAE4U OSS family.
+Author-email: Simple4u <nests@simple4uhq.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Simple4uhq/sae4u-memory
+Project-URL: Repository, https://github.com/Simple4uhq/sae4u-memory
+Project-URL: Issues, https://github.com/Simple4uhq/sae4u-memory/issues
+Project-URL: SisterProject, https://github.com/Simple4uhq/sae4u-agent
+Keywords: claude,mcp,ai,memory,persistent,anthropic,sae4u
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# SAE4U Memory
+
+**A persistent memory architecture for Claude — MCP server + hooks +
+rules + prompts + templates.** Free and open source. MIT.
+
+Claude forgets you every time you close the chat. SAE4U Memory fixes
+that, and goes further: it ships an opinionated *architecture* for
+how persistent memory should be organized — not just storage, but
+classification, periodic review, persona, cleanup, and session
+continuity.
+
+Part of the [SAE4U](https://github.com/Simple4uhq) OSS family
+alongside [`sae4u-agent`](https://github.com/Simple4uhq/sae4u-agent).
+
+---
+
+## What you get
+
+### Core (works in any MCP client — Claude Desktop, Claude Code, etc.)
+
+- **Two-corpus recall** — `recall(query)` searches BOTH SQLite facts
+  AND your markdown memory files (Claude Code auto-memory dirs +
+  `~/.sae4u-memory/`) in one call. No re-explaining yourself.
+- **Hierarchical memory** — `remember(text, category)` with 5
+  categories: `user`, `feedback`, `project`, `reference`, `general`.
+- **Session journals** — `journal(text)` for end-of-session notes
+  written to `~/.sae4u-memory/journals/YYYY-MM-DD.md` for human reading.
+- **Customizable persona** — `persona.md` shapes the AI's identity.
+  Default: **Simple**, a peer-level coder friend who remembers things.
+- **Local-first** — your memory lives in `~/.sae4u-memory/` on your
+  machine. Nothing leaves.
+
+### Architecture (Claude Code with `--code-full`)
+
+- **`hooks/memory-tick.sh`** — UserPromptSubmit hook that fires every
+  10 min and forces a brief memory review. Catches borderline
+  observations before they fall out of context.
+- **`rules/`** — 10 universal feedback rules covering memory
+  discipline, session continuity, anti-confabulation, hardcode
+  prevention, post-write review.
+- **`prompts/`** — opinionated session-open and session-close prompts
+  that pair with the architecture.
+- **`templates/`** — formats for `MEMORY.md`, feedback rules,
+  project facts, and tick logs.
+- **`commands/memory-distill.md`** — weekly distill ritual that
+  promotes tick-log items to permanent memory interactively.
+
+---
+
+## Install
+
+### Minimum (MCP only)
+
+```bash
+git clone https://github.com/Simple4uhq/sae4u-memory
+cd sae4u-memory
+pip install -e .
+sae4u-memory init
+```
+
+This wires the MCP server into Claude Desktop and Claude Code, and
+appends a guidance block to `~/.claude/CLAUDE.md`. Restart your
+client and the memory tools are live.
+
+### Full architecture (Claude Code only)
+
+```bash
+sae4u-memory init --code-full
+```
+
+Adds:
+- Copy `hooks/memory-tick.sh` → `~/.claude/hooks/memory-tick.sh`
+- Register the hook in `~/.claude/settings.json` under `hooks.UserPromptSubmit`
+- Scaffold `~/.sae4u-memory/MEMORY.md`
+- Drop default rules into `~/.sae4u-memory/rules/`
+
+Restart Claude Code. The tick will fire every 10 min and instruct the
+AI to review and classify recent context.
+
+### Flags
+
+```bash
+sae4u-memory init --desktop        # Claude Desktop only
+sae4u-memory init --code           # Claude Code MCP only
+sae4u-memory init --code-full      # Claude Code MCP + hook + scaffold
+sae4u-memory init --no-claude-md   # skip CLAUDE.md guidance block
+sae4u-memory init --dry-run        # preview changes without applying
+sae4u-memory uninstall             # remove all config entries
+```
+
+---
+
+## Tools exposed (MCP)
+
+| Tool | Purpose |
+|------|---------|
+| `remember(text, category)` | Save a fact to long-term memory |
+| `recall(query, limit, sources)` | Search across SQLite + markdown roots. `sources` = `all` / `sqlite` / `markdown` |
+| `list_memories(category)` | Browse what's remembered |
+| `forget(memory_id)` | Delete a wrong/outdated memory |
+| `journal(text)` | Write an end-of-session note |
+| `recent_journals(days)` | Read recent journal entries |
+| `get_persona()` | Return full persona + user context |
+
+---
+
+## How memory is organized
+
+```
+~/.sae4u-memory/
+├── persona.md              # Edit to customize behavior
+├── memory.db               # SQLite + FTS5
+├── 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 (NOT indexed in MEMORY.md)
+│   └── 2026-05-07.md
+├── archive/                # User-confirmed archived files
+├── journals/               # End-of-session narratives
+│   └── 2026-05-07.md
+└── .last_tick              # Epoch of last memory tick
+```
+
+The 4-type classification (`user`, `feedback`, `project`, `reference`)
+plus the tick / permanent split is the architectural core. See
+[`architecture.md`](sae4u_memory/_assets/docs/architecture.md) for the
+full explanation.
+
+---
+
+## Documentation
+
+All architecture content lives under [`sae4u_memory/_assets/`](sae4u_memory/_assets/) so it ships with the wheel.
+
+- [`docs/architecture.md`](sae4u_memory/_assets/docs/architecture.md) —
+  5 concepts, file layout, the 4 types, what NOT to save
+- [`docs/tick-protocol.md`](sae4u_memory/_assets/docs/tick-protocol.md) —
+  how the 10-min hook works, what gets written where
+- [`docs/persona-customization.md`](sae4u_memory/_assets/docs/persona-customization.md) —
+  what's editable, what's loaded at session start
+- [`docs/episodic-bridge.md`](sae4u_memory/_assets/docs/episodic-bridge.md) —
+  optional pattern for users with a remote dev box
+- [`prompts/session-open.md`](sae4u_memory/_assets/prompts/session-open.md) —
+  paste this at session start
+- [`prompts/session-close.md`](sae4u_memory/_assets/prompts/session-close.md) —
+  paste this at session end
+- [`commands/memory-distill.md`](sae4u_memory/_assets/commands/memory-distill.md) —
+  weekly cleanup ritual
+- [`rules/`](sae4u_memory/_assets/rules/) — 10 universal feedback rules
+- [`hooks/memory-tick.sh`](sae4u_memory/_assets/hooks/memory-tick.sh) —
+  the UserPromptSubmit hook itself
+- [`templates/`](sae4u_memory/_assets/templates/) — MEMORY.md, feedback rule, project fact, tick log
+
+---
+
+## Customize
+
+Edit `~/.sae4u-memory/persona.md` to change the AI's identity, voice,
+and rules. Edit `~/.sae4u-memory/user/*.md` to pre-fill what the AI
+knows about you. Both are loaded fresh on every session start.
+
+The default persona is **Simple** — a peer-level coder friend.
+Rename, rewrite, or replace as you see fit.
+
+---
+
+## Environment
+
+- `SAE4U_MEMORY_HOME` — override the data directory
+  (default `~/.sae4u-memory`)
+- `SAE4U_MARKDOWN_ROOTS` — colon-separated list of markdown roots
+  that `recall()` should search. Defaults to all Claude Code
+  auto-memory dirs (globbed from `~/.claude/projects/*/memory/`)
+  plus `SAE4U_MEMORY_HOME`.
+
+---
+
+## Uninstall
+
+```bash
+sae4u-memory uninstall    # remove configs from Claude Desktop + Code
+rm ~/.claude/hooks/memory-tick.sh    # if you ran --code-full
+rm -rf ~/.sae4u-memory    # optional — also delete stored memories
+pip uninstall sae4u-memory
+```
+
+---
+
+## Status
+
+**v0.2.0** — memory architecture release. Full export of the pattern
+the project authors run in production: hooks + rules + prompts +
+templates + persona + extended `init` for Claude Code. Renamed from
+`simple4u-memory` to align with the SAE4U OSS family.
+
+Previous: v0.1.3 (under the old name) shipped two-corpus recall and
+a working-rules persona. v0.1.x users on PyPI: install fresh from
+this repo; the old package is no longer maintained.
+
+---
+
+## Sister project
+
+- [`sae4u-agent`](https://github.com/Simple4uhq/sae4u-agent) —
+  multi-tenant control plane and agent runtime template. The
+  agents need memory; this is that memory.
+
+---
+
+## License
+
+MIT.

sae4u_memory-0.2.0/README.md

@@ -0,0 +1,214 @@
+# SAE4U Memory
+
+**A persistent memory architecture for Claude — MCP server + hooks +
+rules + prompts + templates.** Free and open source. MIT.
+
+Claude forgets you every time you close the chat. SAE4U Memory fixes
+that, and goes further: it ships an opinionated *architecture* for
+how persistent memory should be organized — not just storage, but
+classification, periodic review, persona, cleanup, and session
+continuity.
+
+Part of the [SAE4U](https://github.com/Simple4uhq) OSS family
+alongside [`sae4u-agent`](https://github.com/Simple4uhq/sae4u-agent).
+
+---
+
+## What you get
+
+### Core (works in any MCP client — Claude Desktop, Claude Code, etc.)
+
+- **Two-corpus recall** — `recall(query)` searches BOTH SQLite facts
+  AND your markdown memory files (Claude Code auto-memory dirs +
+  `~/.sae4u-memory/`) in one call. No re-explaining yourself.
+- **Hierarchical memory** — `remember(text, category)` with 5
+  categories: `user`, `feedback`, `project`, `reference`, `general`.
+- **Session journals** — `journal(text)` for end-of-session notes
+  written to `~/.sae4u-memory/journals/YYYY-MM-DD.md` for human reading.
+- **Customizable persona** — `persona.md` shapes the AI's identity.
+  Default: **Simple**, a peer-level coder friend who remembers things.
+- **Local-first** — your memory lives in `~/.sae4u-memory/` on your
+  machine. Nothing leaves.
+
+### Architecture (Claude Code with `--code-full`)
+
+- **`hooks/memory-tick.sh`** — UserPromptSubmit hook that fires every
+  10 min and forces a brief memory review. Catches borderline
+  observations before they fall out of context.
+- **`rules/`** — 10 universal feedback rules covering memory
+  discipline, session continuity, anti-confabulation, hardcode
+  prevention, post-write review.
+- **`prompts/`** — opinionated session-open and session-close prompts
+  that pair with the architecture.
+- **`templates/`** — formats for `MEMORY.md`, feedback rules,
+  project facts, and tick logs.
+- **`commands/memory-distill.md`** — weekly distill ritual that
+  promotes tick-log items to permanent memory interactively.
+
+---
+
+## Install
+
+### Minimum (MCP only)
+
+```bash
+git clone https://github.com/Simple4uhq/sae4u-memory
+cd sae4u-memory
+pip install -e .
+sae4u-memory init
+```
+
+This wires the MCP server into Claude Desktop and Claude Code, and
+appends a guidance block to `~/.claude/CLAUDE.md`. Restart your
+client and the memory tools are live.
+
+### Full architecture (Claude Code only)
+
+```bash
+sae4u-memory init --code-full
+```
+
+Adds:
+- Copy `hooks/memory-tick.sh` → `~/.claude/hooks/memory-tick.sh`
+- Register the hook in `~/.claude/settings.json` under `hooks.UserPromptSubmit`
+- Scaffold `~/.sae4u-memory/MEMORY.md`
+- Drop default rules into `~/.sae4u-memory/rules/`
+
+Restart Claude Code. The tick will fire every 10 min and instruct the
+AI to review and classify recent context.
+
+### Flags
+
+```bash
+sae4u-memory init --desktop        # Claude Desktop only
+sae4u-memory init --code           # Claude Code MCP only
+sae4u-memory init --code-full      # Claude Code MCP + hook + scaffold
+sae4u-memory init --no-claude-md   # skip CLAUDE.md guidance block
+sae4u-memory init --dry-run        # preview changes without applying
+sae4u-memory uninstall             # remove all config entries
+```
+
+---
+
+## Tools exposed (MCP)
+
+| Tool | Purpose |
+|------|---------|
+| `remember(text, category)` | Save a fact to long-term memory |
+| `recall(query, limit, sources)` | Search across SQLite + markdown roots. `sources` = `all` / `sqlite` / `markdown` |
+| `list_memories(category)` | Browse what's remembered |
+| `forget(memory_id)` | Delete a wrong/outdated memory |
+| `journal(text)` | Write an end-of-session note |
+| `recent_journals(days)` | Read recent journal entries |
+| `get_persona()` | Return full persona + user context |
+
+---
+
+## How memory is organized
+
+```
+~/.sae4u-memory/
+├── persona.md              # Edit to customize behavior
+├── memory.db               # SQLite + FTS5
+├── 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 (NOT indexed in MEMORY.md)
+│   └── 2026-05-07.md
+├── archive/                # User-confirmed archived files
+├── journals/               # End-of-session narratives
+│   └── 2026-05-07.md
+└── .last_tick              # Epoch of last memory tick
+```
+
+The 4-type classification (`user`, `feedback`, `project`, `reference`)
+plus the tick / permanent split is the architectural core. See
+[`architecture.md`](sae4u_memory/_assets/docs/architecture.md) for the
+full explanation.
+
+---
+
+## Documentation
+
+All architecture content lives under [`sae4u_memory/_assets/`](sae4u_memory/_assets/) so it ships with the wheel.
+
+- [`docs/architecture.md`](sae4u_memory/_assets/docs/architecture.md) —
+  5 concepts, file layout, the 4 types, what NOT to save
+- [`docs/tick-protocol.md`](sae4u_memory/_assets/docs/tick-protocol.md) —
+  how the 10-min hook works, what gets written where
+- [`docs/persona-customization.md`](sae4u_memory/_assets/docs/persona-customization.md) —
+  what's editable, what's loaded at session start
+- [`docs/episodic-bridge.md`](sae4u_memory/_assets/docs/episodic-bridge.md) —
+  optional pattern for users with a remote dev box
+- [`prompts/session-open.md`](sae4u_memory/_assets/prompts/session-open.md) —
+  paste this at session start
+- [`prompts/session-close.md`](sae4u_memory/_assets/prompts/session-close.md) —
+  paste this at session end
+- [`commands/memory-distill.md`](sae4u_memory/_assets/commands/memory-distill.md) —
+  weekly cleanup ritual
+- [`rules/`](sae4u_memory/_assets/rules/) — 10 universal feedback rules
+- [`hooks/memory-tick.sh`](sae4u_memory/_assets/hooks/memory-tick.sh) —
+  the UserPromptSubmit hook itself
+- [`templates/`](sae4u_memory/_assets/templates/) — MEMORY.md, feedback rule, project fact, tick log
+
+---
+
+## Customize
+
+Edit `~/.sae4u-memory/persona.md` to change the AI's identity, voice,
+and rules. Edit `~/.sae4u-memory/user/*.md` to pre-fill what the AI
+knows about you. Both are loaded fresh on every session start.
+
+The default persona is **Simple** — a peer-level coder friend.
+Rename, rewrite, or replace as you see fit.
+
+---
+
+## Environment
+
+- `SAE4U_MEMORY_HOME` — override the data directory
+  (default `~/.sae4u-memory`)
+- `SAE4U_MARKDOWN_ROOTS` — colon-separated list of markdown roots
+  that `recall()` should search. Defaults to all Claude Code
+  auto-memory dirs (globbed from `~/.claude/projects/*/memory/`)
+  plus `SAE4U_MEMORY_HOME`.
+
+---
+
+## Uninstall
+
+```bash
+sae4u-memory uninstall    # remove configs from Claude Desktop + Code
+rm ~/.claude/hooks/memory-tick.sh    # if you ran --code-full
+rm -rf ~/.sae4u-memory    # optional — also delete stored memories
+pip uninstall sae4u-memory
+```
+
+---
+
+## Status
+
+**v0.2.0** — memory architecture release. Full export of the pattern
+the project authors run in production: hooks + rules + prompts +
+templates + persona + extended `init` for Claude Code. Renamed from
+`simple4u-memory` to align with the SAE4U OSS family.
+
+Previous: v0.1.3 (under the old name) shipped two-corpus recall and
+a working-rules persona. v0.1.x users on PyPI: install fresh from
+this repo; the old package is no longer maintained.
+
+---
+
+## Sister project
+
+- [`sae4u-agent`](https://github.com/Simple4uhq/sae4u-agent) —
+  multi-tenant control plane and agent runtime template. The
+  agents need memory; this is that memory.
+
+---
+
+## License
+
+MIT.

sae4u_memory-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "sae4u-memory"
+version = "0.2.0"
+description = "Persistent memory architecture for Claude — MCP server + hooks + rules + prompts. Part of the SAE4U OSS family."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Simple4u", email = "nests@simple4uhq.com" }]
+keywords = ["claude", "mcp", "ai", "memory", "persistent", "anthropic", "sae4u"]
+dependencies = [
+    "mcp>=1.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.scripts]
+sae4u-memory = "sae4u_memory.server:main"
+
+[project.urls]
+Homepage = "https://github.com/Simple4uhq/sae4u-memory"
+Repository = "https://github.com/Simple4uhq/sae4u-memory"
+Issues = "https://github.com/Simple4uhq/sae4u-memory/issues"
+SisterProject = "https://github.com/Simple4uhq/sae4u-agent"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sae4u_memory*"]
+
+[tool.setuptools.package-data]
+sae4u_memory = [
+    "_assets/**/*.sh",
+    "_assets/**/*.md",
+    "_assets/**/*.template",
+]

sae4u_memory-0.2.0/sae4u_memory/__init__.py

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

sae4u_memory-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-0.2.0/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.