feat(memory): add lifecycle controls (#144)

fixes #109

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: BunsDev

docs/advanced.md

@@ -601,6 +601,11 @@ Additional hosted invariants:
   remote tombstone always applies over local content, a local tombstone is
   never resurrected by a pull, and a file deleted locally after a sync is not
   silently re-created.
+- `coven-code memory` exposes operator controls for hosted memory lifecycle
+  administration: list entries by directory or hosted tenant/repo/domain,
+  expire entries, redact/delete by id or path, delete hosted scopes, and export
+  a tombstone-only audit ledger. The ledger includes timestamps and reason
+  stubs but not original redacted or deleted content.
 - A key with an unresolved team-memory pull conflict is blocked from further
   sync until the persisted conflict record under `.conflicts/` is resolved.
 - `/review` injects the ids and trust labels of every loaded memory entry into

docs/commands.md

@@ -1240,6 +1240,7 @@ are CLI-only.
 | `pr-comments` | Get comments from a GitHub PR. |
 | `ultraplan` | Launch the Ultraplan agentic code planner with extended thinking. |
 | `stats` | Aggregate token / cost / tool stats across saved sessions (in the TUI, `/usage stats` opens the stats dialog). |
+| `memory` | Operator controls for hosted/local memory lifecycle: list, expire, redact, delete, and export the tombstone audit ledger. |
 
 ---
 

docs/configuration.md

@@ -384,6 +384,17 @@ Frontmatter fields:
 | `deleted_at` | Marks memory as deleted. Hosted review excludes deleted entries from prompt loading. |
 | `created_at`, `created_by`, `session_id`, `transcript_ref`, `confidence` | Optional provenance fields for audit and review artifacts. |
 
+Retention defaults apply only when `expires_at` is absent. Hosted review treats
+the effective expiry as `created_at + default window`; malformed dates fail open
+the same way as explicit expiry parsing, so operators should use `YYYY-MM-DD`.
+
+| Retention class | Default window | Operator behavior |
+|-----------------|----------------|-------------------|
+| `standard` | No automatic expiry | Active until explicitly expired, redacted, or deleted. |
+| `short_lived` | 30 days from `created_at` | Automatically excluded from hosted loads after the default window. |
+| `security` | 90 days from `created_at` | Used for redaction stubs and security-sensitive audit records. |
+| `legal_hold` | No automatic expiry | Never auto-expires; `memory expire` and `memory delete` require `--force`. |
+
 Local mode tolerates missing metadata for backward compatibility. Hosted review
 mode treats missing trust as `unknown`, ignores expired memory, and excludes
 memory below the configured trust threshold. Tagged hosted memory is injected
@@ -402,6 +413,20 @@ conflict record is written for operator review instead of overwriting local
 memory. Hosted team-memory sync also sends tenant, installation, repo, and
 domain scope metadata so the server can authorize the full tuple.
 
+### Memory lifecycle operator controls
+
+Use `coven-code memory` to inspect and administer local and hosted memory
+without exposing redacted or deleted content to the model.
+
+| Command | Purpose |
+|---------|---------|
+| `coven-code memory list [--dir <path>] [--tenant <id>] [--repo <id>] [--domain <name>] [--json]` | List memory id, path, retention class, trust, created time, effective expiry, and status. With no `--dir`, scans the project auto-memory directory plus hosted scopes under the Coven Code config directory. |
+| `coven-code memory expire <id-or-path> [--at YYYY-MM-DD] [--force]` | Set `expires_at` in frontmatter. Defaults to today and refuses `legal_hold` entries unless `--force` is present. |
+| `coven-code memory redact <id-or-path> --reason <text>` | Replace the file with a redaction tombstone stub via `redact_memory_file`; the original body is removed. |
+| `coven-code memory delete <id-or-path> --reason <text> [--force]` | Replace the file with a deletion tombstone stub. `legal_hold` entries require `--force`. |
+| `coven-code memory delete --scope tenant=<t>,install=<i>,repo=<r>[,domain=<d>] --reason <text> [--force]` | Remove the hosted memory directory for a scoped tenant/installation/repo/domain. Scope deletion refuses legal-hold files unless forced. |
+| `coven-code memory ledger [--dir <path>] [--json]` | Export tombstoned entries only: id, path, redacted/deleted timestamp, retention class, tombstone reason line, and provenance source. The ledger reads tombstone stubs and never includes original memory body content. |
+
 ### @include directives
 
 AGENTS.md files support `@include` to pull in content from other files:

docs/src/content/configuration.js

@@ -92,6 +92,10 @@ export function render() {
   }
 }</code></pre>
 
+    <h2>Memory Retention</h2>
+    <p>AGENTS.md frontmatter supports lifecycle fields for hosted review memory. <code>expires_at</code> uses <code>YYYY-MM-DD</code> and always wins over retention defaults. <code>retention_class</code> can be <code>standard</code> (no automatic expiry), <code>short_lived</code> (30 days from <code>created_at</code>), <code>security</code> (90 days), or <code>legal_hold</code> (no automatic expiry and requires <code>--force</code> for operator expiry/deletion).</p>
+    <p>Operators can run <code>coven-code memory list</code>, <code>expire</code>, <code>redact</code>, <code>delete</code>, and <code>ledger --json</code>. Redaction and deletion write tombstone stubs; the audit ledger exports ids, timestamps, reasons, and provenance without original removed content.</p>
+
     <h2>Environment Variables</h2>
 
     <table>

src-rust/crates/cli/src/main.rs

@@ -10,6 +10,7 @@
 
 mod codex_oauth_flow;
 mod headless;
+mod memory_admin;
 mod oauth_flow;
 mod stream_mode;
 mod upgrade;
@@ -444,6 +445,11 @@ async fn main() -> anyhow::Result<()> {
         return run_models_command(&raw_args[2..]).await;
     }
 
+    // Fast-path: `coven-code memory ...` — inspect and administer memory lifecycle controls.
+    if raw_args.get(1).map(|s| s.as_str()) == Some("memory") {
+        return memory_admin::handle_memory_command(&raw_args[2..]).await;
+    }
+
     // Fast-path: named commands (`claude agents`, `claude ide`, `claude branch`, …)
     // Check before Cli::parse() so these names don't conflict with positional prompt arg.
     if let Some(cmd_name) = raw_args.get(1).map(|s| s.as_str()) {