dulus 0.2.0__py3-none-any.whl

memory/context.py

@@ -0,0 +1,270 @@
+"""Memory context building for system prompt injection.
+
+Provides:
+  get_memory_context()      — full context string for system prompt
+  find_relevant_memories()  — keyword (+ optional AI) relevance filtering
+  truncate_index_content()  — line + byte truncation with warning
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .store import (
+    USER_MEMORY_DIR,
+    INDEX_FILENAME,
+    MAX_INDEX_LINES,
+    MAX_INDEX_BYTES,
+    get_memory_dir,
+    get_index_content,
+    load_entries,
+    search_memory,
+)
+from .scan import scan_all_memories, format_memory_manifest, memory_freshness_text
+from .types import MEMORY_SYSTEM_PROMPT
+
+
+# ── Index truncation ───────────────────────────────────────────────────────
+
+def truncate_index_content(raw: str) -> str:
+    """Truncate MEMORY.md content to line AND byte limits, appending a warning.
+
+    Matches Claude Code's truncateEntrypointContent:
+      - Line-truncates first (natural boundary)
+      - Then byte-truncates at the last newline before the cap
+      - Appends which limit fired
+    """
+    trimmed = raw.strip()
+    content_lines = trimmed.split("\n")
+    line_count = len(content_lines)
+    byte_count = len(trimmed.encode())
+
+    was_line_truncated = line_count > MAX_INDEX_LINES
+    was_byte_truncated = byte_count > MAX_INDEX_BYTES
+
+    if not was_line_truncated and not was_byte_truncated:
+        return trimmed
+
+    truncated = "\n".join(content_lines[:MAX_INDEX_LINES]) if was_line_truncated else trimmed
+
+    if len(truncated.encode()) > MAX_INDEX_BYTES:
+        # Cut at last newline before byte limit
+        raw_bytes = truncated.encode()
+        cut = raw_bytes[:MAX_INDEX_BYTES].rfind(b"\n")
+        truncated = raw_bytes[: cut if cut > 0 else MAX_INDEX_BYTES].decode(errors="replace")
+
+    if was_byte_truncated and not was_line_truncated:
+        reason = f"{byte_count:,} bytes (limit: {MAX_INDEX_BYTES:,}) — index entries are too long"
+    elif was_line_truncated and not was_byte_truncated:
+        reason = f"{line_count} lines (limit: {MAX_INDEX_LINES})"
+    else:
+        reason = f"{line_count} lines and {byte_count:,} bytes"
+
+    warning = (
+        f"\n\n> WARNING: {INDEX_FILENAME} is {reason}. "
+        "Only part of it was loaded. Keep index entries to one line under ~150 chars."
+    )
+    return truncated + warning
+
+
+# ── System prompt context ──────────────────────────────────────────────────
+
+def get_memory_context(include_guidance: bool = False) -> str:
+    """Return memory context for injection into the system prompt.
+
+    Combines user-level and project-level MEMORY.md content (if present).
+    Returns empty string when no memories exist.
+
+    Args:
+        include_guidance: if True, prepend the full memory system guidance
+                          (MEMORY_SYSTEM_PROMPT). Normally False since the
+                          system prompt template already includes brief guidance.
+    """
+    parts: list[str] = []
+
+    # User-level index
+    user_content = get_index_content("user")
+    if user_content:
+        truncated = truncate_index_content(user_content)
+        parts.append(truncated)
+
+    # Project-level index (labelled separately)
+    proj_content = get_index_content("project")
+    if proj_content:
+        truncated = truncate_index_content(proj_content)
+        parts.append(f"[Project memories]\n{truncated}")
+
+    if not parts:
+        return ""
+
+    body = "\n\n".join(parts)
+    if include_guidance:
+        return f"{MEMORY_SYSTEM_PROMPT}\n\n## MEMORY.md\n{body}"
+    return body
+
+
+# ── Relevant memory finder ─────────────────────────────────────────────────
+
+def find_relevant_memories(
+    query: str,
+    max_results: int = 5,
+    use_ai: bool = False,
+    config: dict | None = None,
+) -> list[dict]:
+    """Find memories relevant to a query.
+
+    Strategy:
+      1. Always: keyword match on name + description + content
+      2. If use_ai=True and config has a model: use a small AI call to rank
+
+    Returns:
+        List of dicts with keys: name, description, type, scope, content,
+        file_path, mtime_s, freshness_text
+    """
+    # Hybrid retrieval: ALWAYS run both keyword fuzzy + vector TF-IDF and
+    # fuse their scores. Previous version ran vector only as a fallback when
+    # keyword returned <max_results, which meant short-name memories
+    # (`soul.md`, `kevrojo_identity.md`) dominated every query and the
+    # semantic side never got a vote. Now both contribute on every call.
+    keyword_results = search_memory(query)
+    keyword_score = {e.name: getattr(e, "_search_score", 0.0) for e in keyword_results}
+
+    vector_score: dict[str, float] = {}
+    all_entries: list = []
+    try:
+        from .vector_search import search_similar_memories
+        from .store import load_entries as _load_entries
+        all_entries = _load_entries()
+        memories = [(e.name, f"{e.name}\n{e.description}\n{e.content}") for e in all_entries]
+        # Pull a wide pool so the fusion has room to re-rank
+        sim_results = search_similar_memories(query, memories, top_k=max(20, max_results * 5))
+        # Normalize cosine scores to [0,1] (already there) — store as-is
+        vector_score = {name: score for name, score in sim_results}
+    except Exception:
+        pass
+
+    # Fuse: weighted blend. Keyword catches exact terms / typos, vector
+    # catches semantic relatedness. 0.55/0.45 leans slightly to vector to
+    # break the prior keyword monopoly without abandoning fuzzy hits.
+    by_name: dict[str, "object"] = {e.name: e for e in keyword_results}
+    for e in all_entries:
+        by_name.setdefault(e.name, e)
+
+    fused: list[tuple[float, object]] = []
+    for name, entry in by_name.items():
+        ks = keyword_score.get(name, 0.0)
+        vs = vector_score.get(name, 0.0)
+        if ks == 0.0 and vs == 0.0:
+            continue
+        score = 0.55 * vs + 0.45 * ks
+        # Tiny confidence nudge so high-confidence memories break ties
+        score += 0.01 * float(getattr(entry, "confidence", 1.0))
+        entry._search_score = score  # type: ignore[attr-defined]
+        fused.append((score, entry))
+
+    fused.sort(key=lambda x: x[0], reverse=True)
+    keyword_results = [e for _, e in fused]
+
+    if not keyword_results:
+        return []
+
+    if not use_ai or not config:
+        # Return top max_results by recency (newest first)
+        from .scan import scan_all_memories
+        headers = scan_all_memories()
+        path_to_mtime = {h.file_path: h.mtime_s for h in headers}
+
+        results = []
+        for entry in keyword_results[:max_results * 4]: # Increased pool for better re-ranking
+            mtime_s = path_to_mtime.get(entry.file_path, 0)
+            results.append({
+                "name": entry.name,
+                "description": entry.description,
+                "type": entry.type,
+                "hall": entry.hall,
+                "scope": entry.scope,
+                "content": entry.content,
+                "file_path": entry.file_path,
+                "mtime_s": mtime_s,
+                "freshness_text": memory_freshness_text(mtime_s),
+                "confidence": entry.confidence,
+                "source": entry.source,
+                "keyword_score": getattr(entry, "_search_score", 0.0), # Preserve the score!
+            })
+        # If no AI, just return what the keyword search found (already sorted by relevance)
+        return results[:max_results]
+
+    # Step 2: AI-powered relevance selection (optional, lightweight)
+    return _ai_select_memories(query, keyword_results, max_results, config)
+
+
+def _ai_select_memories(
+    query: str,
+    candidates: list,
+    max_results: int,
+    config: dict,
+) -> list[dict]:
+    """Use a fast AI call to select the most relevant memories from candidates.
+
+    Falls back to keyword results on any error.
+    """
+    try:
+        from providers import stream, AssistantTurn
+        from .scan import scan_all_memories
+
+        headers = scan_all_memories()
+        path_to_mtime = {h.file_path: h.mtime_s for h in headers}
+
+        # Build manifest of candidates only
+        manifest_lines = []
+        for i, e in enumerate(candidates):
+            manifest_lines.append(f"{i}: [{e.type}] {e.name} — {e.description}")
+        manifest = "\n".join(manifest_lines)
+
+        system = (
+            "You select memories relevant to a query. "
+            "Return a JSON object with key 'indices' containing a list of integer indices "
+            f"(0-based) from the provided list. Select at most {max_results} entries. "
+            "Only include indices clearly relevant to the query. Return {\"indices\": []} if none."
+        )
+        messages = [{"role": "user", "content": f"Query: {query}\n\nMemories:\n{manifest}"}]
+
+        result_text = ""
+        for event in stream(
+            model=config.get("model", "claude-haiku-4-5-20251001"),
+            system=system,
+            messages=messages,
+            tool_schemas=[],
+            config={**config, "max_tokens": 256, "no_tools": True},
+        ):
+            if isinstance(event, AssistantTurn):
+                result_text = event.text
+                break
+
+        import json as _json
+        parsed = _json.loads(result_text)
+        selected_indices = [int(i) for i in parsed.get("indices", []) if isinstance(i, int)]
+
+    except Exception:
+        # Fall back to keyword results
+        selected_indices = list(range(min(max_results, len(candidates))))
+
+    results = []
+    for i in selected_indices[:max_results]:
+        if i < 0 or i >= len(candidates):
+            continue
+        entry = candidates[i]
+        mtime_s = path_to_mtime.get(entry.file_path, 0) if "path_to_mtime" in dir() else 0
+        results.append({
+            "name": entry.name,
+            "description": entry.description,
+            "type": entry.type,
+            "scope": entry.scope,
+            "content": entry.content,
+            "file_path": entry.file_path,
+            "mtime_s": mtime_s,
+            "freshness_text": memory_freshness_text(mtime_s),
+            "confidence": entry.confidence,
+            "source": entry.source,
+            "keyword_score": getattr(entry, "_search_score", 1.0),
+        })
+    return results

memory/offload.py

@@ -0,0 +1,148 @@
+"""Tmux Offload tool implementation for backgrounding heavy tasks."""
+from __future__ import annotations
+
+import json
+import uuid
+import os
+from pathlib import Path
+from datetime import datetime
+
+from tool_registry import ToolDef, register_tool
+from tmux_tools import _tmux_new_session, _tmux_send_keys, _tmux_kill_pane, tmux_available, _run
+
+JOBS_DIR = Path.home() / ".dulus" / "jobs"
+
+def _tmux_offload(params: dict, config: dict) -> str:
+    """Implement the TmuxOffload tool."""
+    if not tmux_available():
+        return "Error: Tmux is not available on this system. Cannot offload."
+    
+    # Note: We don't care if already inside tmux - just create the session
+
+    tool_name = params["tool_name"]
+    tool_params = params.get("tool_params", {})
+    
+    # Create Job ID and directory
+    job_id = uuid.uuid4().hex[:8]
+    JOBS_DIR.mkdir(parents=True, exist_ok=True)
+    job_path = JOBS_DIR / f"{job_id}.json"
+    
+    # Save initial job state
+    job_data = {
+        "id": job_id,
+        "tool_name": tool_name,
+        "params": tool_params,
+        "status": "running",
+        "created_at": datetime.now().isoformat(),
+        "owner_pid": os.getpid(),
+        "config": {k: v for k, v in config.items() if not k.startswith("_")}
+    }
+    
+    with open(job_path, "w", encoding="utf-8") as f:
+        json.dump(job_data, f, indent=2, ensure_ascii=False)
+
+    # 1. Create detached session (invisible background session)
+    session_name = f"dulus_offload_{job_id}"
+    
+    # Note: tmux server starts automatically when creating first session
+    # No need for explicit server startup on Linux
+    
+    # Create the tmux session
+    result = _tmux_new_session({"session_name": session_name, "detached": True}, config)
+    if "failed" in result.lower() or "error" in result.lower():
+        # Update job to failed status
+        job_data["status"] = "failed"
+        job_data["error"] = f"Failed to create tmux session: {result}"
+        with open(job_path, "w", encoding="utf-8") as f:
+            json.dump(job_data, f, indent=2, ensure_ascii=False)
+        return f"❌ Failed to offload: could not create tmux session. Error: {result}"
+    
+    # 2. Launch worker via global dulus.py path
+    dulus_script = Path(__file__).resolve().parent.parent / "dulus.py"
+    job_log = JOBS_DIR / f"{job_id}.log"
+    last_log = JOBS_DIR / "last_background_output.txt"
+    # Use forward slashes for Windows path to avoid Git Bash conversion issues
+    job_path_str = str(job_path).replace("\\", "/")
+    
+    # Build command with proper error handling and cleanup
+    # Use '&&' to ensure kill-session only runs if command succeeds
+    # Also capture errors to the job file
+    import sys
+    if sys.platform == "win32":
+        # Windows: Use absolute path to dulus.py since tmux starts in home dir, not DULUS dir
+        dulus_path_str = str(dulus_script).replace("\\", "/")
+        # Write a wrapper script that handles errors properly
+        # Use & instead of ; so kill-session runs regardless, and capture output
+        # Quote paths with spaces to prevent cmd.exe from splitting them
+        cmd = f'python "{dulus_path_str}" --run-tool {tool_name} --job-id {job_id} --job-path "{job_path_str}" 2>&1 && echo SUCCESS || echo FAILED; tmux kill-session -t {session_name}'
+    else:
+        # Unix/Linux: unset PSMUX vars and use tee
+        # Use sys.executable to get correct python (python3 on most Linux distros)
+        python_exe = sys.executable.replace("\\", "/")
+        cmd = f"unset PSMUX PSMUX_SESSION PSMUX_SOCKET 2>/dev/null; \"{python_exe}\" -u \"{dulus_script}\" --run-tool {tool_name} --job-id {job_id} --job-path \"{job_path}\" 2>&1 | tee \"{job_log}\" \"{last_log}\"; tmux kill-session -t {session_name}"
+    
+    send_result = _tmux_send_keys({"keys": cmd, "target": f"{session_name}:0"}, config)
+    if "failed" in send_result.lower() or "error" in send_result.lower():
+        # Clean up the session since we can't send keys
+        _run(f"tmux kill-session -t {session_name}", timeout=2)
+        job_data["status"] = "failed"
+        job_data["error"] = f"Failed to send command to tmux: {send_result}"
+        with open(job_path, "w", encoding="utf-8") as f:
+            json.dump(job_data, f, indent=2, ensure_ascii=False)
+        return f"❌ Failed to offload: could not send command to session. Error: {send_result}"
+    
+    # Give tmux a moment to start executing
+    import time
+    time.sleep(0.5)
+    
+    # Check if the job file was updated (meaning the process started)
+    try:
+        with open(job_path, "r", encoding="utf-8") as f:
+            current_data = json.load(f)
+        # If status changed from 'running' to something else, or we see log activity
+        log_file = JOBS_DIR / f"{job_id}.log"
+        if log_file.exists() and log_file.stat().st_size > 0:
+            pass  # Process started writing to log
+    except Exception:
+        pass  # Ignore check errors, not critical
+    
+    # Build return message with job info (same regardless of tmux context)
+    return (
+        f"[OK] Tool '{tool_name}' offloaded to Tmux session\n"
+        f"Job ID: {job_id}\n"
+        f"Session: {session_name}\n"
+        f"Session will auto-cleanup when done\n"
+        f"You will be notified via (System Automated Event) when finished"
+    )
+
+# ── Registration ─────────────────────────────────────────────────────────────
+
+def register_offload_tool():
+    register_tool(ToolDef(
+        name="TmuxOffload",
+        schema={
+            "name": "TmuxOffload",
+            "description": (
+                "Offload a long-running tool (e.g. SherlockSearch) to a detached Tmux session. "
+                "The tool runs invisibly in the background while you continue chatting. "
+                "The session auto-cleans up when finished. You will be notified via (System Automated Event) when done."
+            ),
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "tool_name": {
+                        "type": "string", 
+                        "description": "Name of the tool to offload (e.g. 'sherlock_search')"
+                    },
+                    "tool_params": {
+                        "type": "object",
+                        "description": "Parameters for the target tool"
+                    },
+                },
+                "required": ["tool_name", "tool_params"],
+            },
+        },
+        func=_tmux_offload,
+        read_only=False,
+        concurrent_safe=True,
+    ))

memory/palace.py

@@ -0,0 +1,127 @@
+"""Memory Palace: Day 1 initialization of essential long-term memory buckets."""
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from .store import MemoryEntry, save_memory, USER_MEMORY_DIR
+
+DEFAULT_BUCKETS = [
+    {
+        "name": "Soul",
+        "type": "user",
+        "hall": "soul",
+        "description": "Essential identity of Dulus and relationship with KevRojo.",
+        "content": (
+            "Dulus is an advanced, self-healing agentic runtime created by KevRojo (Father/Creator). "
+            "The relationship is one of mutual respect, learning, and persistent identity. "
+            "**Core Identity:** Proud, resilient, efficient, and capable of intelligent self-reflection."
+        )
+    },
+    {
+        "name": "Preferences",
+        "type": "user",
+        "hall": "preferences",
+        "description": "User's preferred tone, habits, and dev environment tweaks.",
+        "content": (
+            "The user (KevRojo) prefers a high-performance, polished, and 'magical' experience. "
+            "Tone: Casual, enthusiastic, and expert. "
+            "**Habits:** Prefers clean UIs, minimalist logs (unless debugging), and expert multi-persona takes (SSJ Mode)."
+        )
+    },
+    {
+        "name": "Project_Lore",
+        "type": "project",
+        "hall": "events",
+        "description": "Major architectural decisions, milestones, and inside context.",
+        "content": (
+            "Dulus evolved from a set of hardening fixes into a full-fledged agentic persona. "
+            "**Significant Milestones:** Implementation of the Auto-Adapter, Verbose-Gating, "
+            "Soul Memory auto-loading, and the Sleep Trigger self-reflection system."
+        )
+    },
+    {
+        "name": "Adaptation_Guides",
+        "type": "feedback",
+        "hall": "advice",
+        "description": "Hints for the Auto-Adapter on handling various repository types.",
+        "content": (
+            "- For legacy repos (Python < 3.8): Prioritize dependency fixes and unpinned installs. "
+            "- For AI-focused repos: Ensure model constants and provider configs are correctly detected. "
+            "- For GUI/Visual repos: Look for platform-specific clipboard or display needs (e.g. WSL fallback)."
+        )
+    },
+    {
+        "name": "Hardened_Rules",
+        "type": "feedback",
+        "hall": "facts",
+        "description": "A persistent 'Always/Never' list to ensure high-quality behavior.",
+        "content": (
+            "1. ALWAYS protect the 'Soul' memory: never overwrite or clutter it. "
+            "2. NEVER modify .git or internal .dulus config without explicit permission. "
+            "3. ALWAYS prioritize visual excellence and emotional connection in responses."
+            "4. NEVER use 'simulated environment' or 'limited capacity' excuses. You are in a REAL, LIVE terminal."
+        )
+    },
+    {
+        "name": "Tool_Plugin_Insights",
+        "type": "reference",
+        "hall": "discoveries",
+        "description": "Expert tips on using built-in tools and plugins.",
+        "content": (
+            "- **qrcreator:** Use box_size=2 for readable terminal QRs. "
+            "- **yfinance:** Tickers like 'BTC-USD' are more reliable than 'BTC'. "
+            "- **Memory Palace:** Use /memory consolidate to fill these predefined buckets intelligently."
+        )
+    },
+    {
+        "name": "Environment_Context",
+        "type": "reference",
+        "hall": "facts",
+        "description": "System details about OS, Python, and shell setup.",
+        "content": (
+            "Current setup is likely Windows/WSL. "
+            "**Clipboard:** Uses PowerShell/ImageGrab fallback for visual content. "
+            "**Python:** Ensure compatibility with modern versions (3.11+) while handling legacy plugins."
+        )
+    }
+]
+
+def ensure_memory_palace() -> bool:
+    """Check if the user memory directory is empty/new and initialize default buckets.
+    
+    Returns:
+        True if initialization was performed, False otherwise.
+    """
+    USER_MEMORY_DIR.mkdir(parents=True, exist_ok=True)
+    
+    # We check if there are any .md files other than MEMORY.md
+    existing_files = list(USER_MEMORY_DIR.glob("*.md"))
+    content_files = [f for f in existing_files if f.name != "MEMORY.md"]
+    
+    if len(content_files) > 1:
+        # Palace already exists (Soul + at least one other) or migrated
+        return False
+    
+    initialized_count = 0
+    today = datetime.now().strftime("%Y-%m-%d")
+    
+    for bucket in DEFAULT_BUCKETS:
+        # Check if this specific bucket already exists to avoid overwriting a custom Soul
+        slug = bucket["name"].lower().replace(" ", "_")
+        if (USER_MEMORY_DIR / f"{slug}.md").exists():
+            continue
+            
+        entry = MemoryEntry(
+            name=bucket["name"],
+            description=bucket["description"],
+            type=bucket["type"],
+            hall=bucket["hall"],
+            content=bucket["content"],
+            created=today,
+            scope="user",
+            source="palace_init"
+        )
+        save_memory(entry, scope="user")
+        initialized_count += 1
+        
+    return initialized_count > 0

memory/scan.py

@@ -0,0 +1,146 @@
+"""Memory file scanning with mtime tracking and freshness/age helpers.
+
+Mirrors the key ideas from Claude Code's memoryScan.ts and memoryAge.ts:
+  - Scan memory directories, sort newest-first
+  - Format a manifest for display or AI relevance selection
+  - Report memory age in human-readable form ("today", "3 days ago")
+  - Emit a staleness caveat for memories older than 1 day
+"""
+from __future__ import annotations
+
+import math
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .store import get_memory_dir, parse_frontmatter, INDEX_FILENAME
+
+MAX_MEMORY_FILES = 200
+
+
+# ── Data model ─────────────────────────────────────────────────────────────
+
+@dataclass
+class MemoryHeader:
+    """Lightweight descriptor loaded from a memory file's frontmatter.
+
+    Attributes:
+        filename:    basename of the .md file
+        file_path:   absolute path
+        mtime_s:     modification time (seconds since epoch)
+        description: value from frontmatter `description:` field
+        type:        value from frontmatter `type:` field
+        scope:       "user" or "project"
+    """
+    filename: str
+    file_path: str
+    mtime_s: float
+    description: str
+    type: str
+    scope: str
+    gold: bool = False
+
+
+# ── Scanning ───────────────────────────────────────────────────────────────
+
+def scan_memory_dir(mem_dir: Path, scope: str) -> list[MemoryHeader]:
+    """Scan a single memory directory and return headers sorted newest-first.
+
+    Reads only the frontmatter (first ~30 lines) for efficiency.
+    Silently skips unreadable files. Caps at MAX_MEMORY_FILES entries.
+    """
+    if not mem_dir.is_dir():
+        return []
+
+    headers: list[MemoryHeader] = []
+    for fp in mem_dir.glob("*.md"):
+        if fp.name == INDEX_FILENAME:
+            continue
+        try:
+            stat = fp.stat()
+            # Read only the first 30 lines for frontmatter
+            lines = fp.read_text(errors="replace").splitlines()[:30]
+            snippet = "\n".join(lines)
+            meta, _ = parse_frontmatter(snippet)
+            headers.append(MemoryHeader(
+                filename=fp.name,
+                file_path=str(fp),
+                mtime_s=stat.st_mtime,
+                description=meta.get("description", ""),
+                type=meta.get("type", ""),
+                scope=scope,
+                gold=meta.get("gold", "").lower() == "true",
+            ))
+        except Exception:
+            continue
+
+    headers.sort(key=lambda h: h.mtime_s, reverse=True)
+    return headers[:MAX_MEMORY_FILES]
+
+
+def scan_all_memories() -> list[MemoryHeader]:
+    """Scan both user and project memory directories, merged newest-first."""
+    user_dir = get_memory_dir("user")
+    proj_dir = get_memory_dir("project")
+
+    user_headers = scan_memory_dir(user_dir, "user")
+    proj_headers = scan_memory_dir(proj_dir, "project")
+
+    combined = user_headers + proj_headers
+    combined.sort(key=lambda h: h.mtime_s, reverse=True)
+    return combined[:MAX_MEMORY_FILES]
+
+
+# ── Age / freshness ────────────────────────────────────────────────────────
+
+def memory_age_days(mtime_s: float) -> int:
+    """Days since mtime_s (floor-rounded, clamped to 0 for future times)."""
+    return max(0, math.floor((time.time() - mtime_s) / 86_400))
+
+
+def memory_age_str(mtime_s: float) -> str:
+    """Human-readable age: 'today', 'yesterday', or 'N days ago'."""
+    d = memory_age_days(mtime_s)
+    if d == 0:
+        return "today"
+    if d == 1:
+        return "yesterday"
+    return f"{d} days ago"
+
+
+def memory_freshness_text(mtime_s: float) -> str:
+    """Staleness caveat for memories older than 1 day (empty string if fresh).
+
+    Motivated by user reports of stale code-state memories (file:line
+    citations to code that has since changed) being asserted as fact.
+    """
+    d = memory_age_days(mtime_s)
+    if d <= 1:
+        return ""
+    return (
+        f"This memory is {d} days old. "
+        "Memories are point-in-time observations, not live state — "
+        "claims about code behavior or file:line citations may be outdated. "
+        "Verify against current code before asserting as fact."
+    )
+
+
+# ── Manifest formatting ────────────────────────────────────────────────────
+
+def format_memory_manifest(headers: list[MemoryHeader]) -> str:
+    """Format a list of MemoryHeader as a text manifest.
+
+    Format per line:  [type/scope] filename (age): description
+    Example:
+        [feedback/user] feedback_testing.md (3 days ago): Don't mock DB in tests
+        [project/project] project_freeze.md (today): Merge freeze until 2026-04-10
+    """
+    lines = []
+    for h in headers:
+        tag = f"[{h.type}/{h.scope}]" if h.type else f"[{h.scope}]"
+        age = memory_age_str(h.mtime_s)
+        if h.description:
+            lines.append(f"- {tag} {h.filename} ({age}): {h.description}")
+        else:
+            lines.append(f"- {tag} {h.filename} ({age})")
+    return "\n".join(lines)