rockycode 0.1.0__py3-none-any.whl

rockycode/memory/index.py

@@ -0,0 +1,260 @@
+"""Semantic memory index: Ollama embeddings in sqlite-vec, FTS5 keyword hybrid.
+
+`index.db` is a disposable cache derived from the markdown files — delete it
+any time, the next search rebuilds it. The files stay the truth (M0 rule).
+
+Two embedding SPACES, every document in both (user setup, verified live
+2026-06-12 — including the cross-lingual case):
+- "en" space: nomic-embed-text (768d) — the precision space for
+  English↔English. REQUIRES `search_document:` / `search_query:` task
+  prefixes; without them quality silently degrades.
+- "zh" space: qwen3-embedding:0.6b (1024d) — multilingual, so a Chinese
+  query matches an English memory here and vice versa.
+
+Storing docs in one language-routed table would break exactly the user's
+real pattern (asking in Chinese about English code facts), so language
+detection only steers query-side weights: English queries trust the nomic
+space first; Chinese queries search only the qwen space (nomic cannot embed
+CJK meaningfully). FTS5 keyword hits join the rank fusion in both cases.
+
+Degradation ladder — search never throws at the caller:
+  Ollama down            → FTS5 keyword search only
+  sqlite-vec won't load  → IndexUnavailable at construction; callers fall
+                           back to the store's substring search (M0 path)
+"""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import os
+import re
+import sqlite3
+import struct
+from pathlib import Path
+from typing import Optional
+
+from rockycode.memory.store import Memory, MemoryStore
+
+OLLAMA_URL = os.getenv("ROCKYCODE_OLLAMA_URL", "http://localhost:11434")
+
+# space → (model, dimensions, document prefix, query prefix)
+EMBED_MODELS = {
+    "en": ("nomic-embed-text", 768, "search_document: ", "search_query: "),
+    "zh": ("qwen3-embedding:0.6b", 1024, "", ""),
+}
+# query language → {space: RRF weight}; FTS5 weight applies to both
+SPACE_WEIGHTS = {
+    "en": {"en": 1.0, "zh": 0.8},
+    "zh": {"zh": 1.0},  # no nomic for CJK queries
+}
+FTS_WEIGHT = 0.8
+MAX_EMBED_CHARS = 4_000
+RRF_K = 60  # standard reciprocal-rank-fusion constant
+
+_CJK = re.compile(r"[぀-ヿ㐀-䶿一-鿿豈-﫿]")
+
+
+class IndexUnavailable(RuntimeError):
+    """sqlite-vec could not be loaded; semantic search is off."""
+
+
+def detect_lang(text: str) -> str:
+    return "zh" if len(_CJK.findall(text[:2000])) >= 2 else "en"
+
+
+def _fts_norm(text: str) -> str:
+    """Space out CJK characters so FTS5's unicode61 tokenizer can index them
+    individually — otherwise a run like 界面颜色只用十六进制 is one opaque
+    token and 颜色 never matches. Queries phrase-match adjacent chars."""
+    return _CJK.sub(lambda m: f" {m.group(0)} ", text)
+
+
+def _pack(vec: list[float]) -> bytes:
+    return struct.pack(f"{len(vec)}f", *vec)
+
+
+def _doc_text(mem: Memory) -> str:
+    return f"{mem.name}\n{mem.description}\n{mem.body}"[:MAX_EMBED_CHARS]
+
+
+def _doc_hash(mem: Memory) -> str:
+    return hashlib.sha256(_doc_text(mem).encode()).hexdigest()[:16]
+
+
+class MemoryIndex:
+    def __init__(
+        self,
+        store: MemoryStore,
+        db_path: Optional[Path] = None,
+        client=None,  # AsyncOpenAI-compatible; tests inject a fake
+    ) -> None:
+        self.store = store
+        self.db_path = db_path or (store.root / ".." / "index.db").resolve()
+        if client is None:
+            from openai import AsyncOpenAI
+
+            client = AsyncOpenAI(base_url=f"{OLLAMA_URL}/v1", api_key="ollama", max_retries=0, timeout=60.0)
+        self.client = client
+        self._conn: Optional[sqlite3.Connection] = None
+
+    def conn(self) -> sqlite3.Connection:
+        if self._conn is not None:
+            return self._conn
+        try:
+            import sqlite_vec
+        except ImportError as e:
+            raise IndexUnavailable(f"sqlite-vec not installed: {e}") from e
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(self.db_path)
+        try:
+            conn.enable_load_extension(True)
+            sqlite_vec.load(conn)
+            conn.enable_load_extension(False)
+        except (AttributeError, sqlite3.OperationalError) as e:
+            conn.close()
+            raise IndexUnavailable(f"could not load sqlite-vec extension: {e}") from e
+        conn.executescript(
+            f"""
+            CREATE TABLE IF NOT EXISTS mem(
+                name TEXT PRIMARY KEY, lang TEXT, hash TEXT, description TEXT);
+            CREATE VIRTUAL TABLE IF NOT EXISTS vec_en USING vec0(emb float[{EMBED_MODELS['en'][1]}]);
+            CREATE VIRTUAL TABLE IF NOT EXISTS vec_zh USING vec0(emb float[{EMBED_MODELS['zh'][1]}]);
+            CREATE VIRTUAL TABLE IF NOT EXISTS fts USING fts5(name, description, body);
+            """
+        )
+        self._conn = conn
+        return conn
+
+    async def _embed(self, lang: str, texts: list[str], *, query: bool = False) -> list[list[float]]:
+        model, _, doc_prefix, query_prefix = EMBED_MODELS[lang]
+        prefix = query_prefix if query else doc_prefix
+        resp = await self.client.embeddings.create(model=model, input=[prefix + t for t in texts])
+        return [d.embedding for d in resp.data]
+
+    def _rowid(self, conn: sqlite3.Connection, name: str) -> Optional[int]:
+        row = conn.execute("SELECT rowid FROM mem WHERE name = ?", (name,)).fetchone()
+        return row[0] if row else None
+
+    def _remove(self, conn: sqlite3.Connection, name: str) -> None:
+        rowid = self._rowid(conn, name)
+        if rowid is None:
+            return
+        for table in ("vec_en", "vec_zh", "fts", "mem"):
+            conn.execute(f"DELETE FROM {table} WHERE rowid = ?", (rowid,))
+
+    async def reindex(self, force: bool = False) -> tuple[int, int, int]:
+        """Sync index.db with the markdown files. Returns (indexed, kept, removed).
+
+        Hash comparison makes the no-change case a few milliseconds, so this
+        runs before every search — the index is always fresh, no manual step.
+        """
+        conn = self.conn()
+        memories = [m for m in self.store.load_all() if m.status == "active"]
+        seen = {m.name for m in memories}
+
+        stale = [
+            name for (name,) in conn.execute("SELECT name FROM mem").fetchall()
+            if name not in seen
+        ]
+        for name in stale:
+            self._remove(conn, name)
+
+        pending: list[Memory] = []
+        kept = 0
+        for mem in memories:
+            row = conn.execute("SELECT hash FROM mem WHERE name = ?", (mem.name,)).fetchone()
+            if not force and row is not None and row[0] == _doc_hash(mem):
+                kept += 1
+                continue
+            pending.append(mem)
+
+        if pending:
+            texts = [_doc_text(m) for m in pending]
+            # every doc goes into BOTH spaces — cross-lingual recall depends on it
+            vectors = {space: await self._embed(space, texts) for space in EMBED_MODELS}
+            for i, mem in enumerate(pending):
+                self._remove(conn, mem.name)
+                cur = conn.execute(
+                    "INSERT INTO mem(name, lang, hash, description) VALUES (?, ?, ?, ?)",
+                    (mem.name, detect_lang(_doc_text(mem)), _doc_hash(mem), mem.description),
+                )
+                rowid = cur.lastrowid
+                for space in EMBED_MODELS:
+                    conn.execute(
+                        f"INSERT INTO vec_{space}(rowid, emb) VALUES (?, ?)",
+                        (rowid, _pack(vectors[space][i])),
+                    )
+                conn.execute(
+                    "INSERT INTO fts(rowid, name, description, body) VALUES (?, ?, ?, ?)",
+                    (rowid, mem.name, _fts_norm(mem.description), _fts_norm(mem.body)),
+                )
+        conn.commit()
+        return len(pending), kept, len(stale)
+
+    def _fts_names(self, query: str, k: int) -> list[str]:
+        # CJK terms become phrase queries over their spaced-out chars
+        # ("颜色" → '"颜 色"'), matching how _fts_norm indexed them.
+        terms = " OR ".join(
+            f'"{" ".join(_fts_norm(t).split())}"' for t in re.findall(r"\w+", query)[:12]
+        )
+        if not terms:
+            return []
+        try:
+            rows = self.conn().execute(
+                "SELECT m.name FROM fts JOIN mem m ON m.rowid = fts.rowid "
+                "WHERE fts MATCH ? ORDER BY rank LIMIT ?",
+                (terms, k),
+            ).fetchall()
+        except sqlite3.OperationalError:
+            return []
+        return [r[0] for r in rows]
+
+    async def search(self, query: str, k: int = 5) -> list[tuple[Memory, float]]:
+        """Hybrid search: both vector tables + FTS5, merged by RRF.
+
+        Ollama being down degrades to keyword-only; this never raises for
+        anything but IndexUnavailable (no sqlite-vec at all).
+        """
+        conn = self.conn()
+        try:
+            await self.reindex()
+        except Exception:  # noqa: BLE001 — embedding refresh is best-effort
+            pass
+
+        # Weighted RRF across spaces. Weights are query-language-dependent
+        # (SPACE_WEIGHTS): KNN always returns k rows however distant, so the
+        # less trustworthy space must not be able to outvote the primary one.
+        rankings: list[tuple[float, list[str]]] = []
+        for space, weight in SPACE_WEIGHTS[detect_lang(query)].items():
+            try:
+                qvec = (await self._embed(space, [query[:MAX_EMBED_CHARS]], query=True))[0]
+            except Exception:  # noqa: BLE001 — Ollama down → keyword only
+                continue
+            rows = conn.execute(
+                f"SELECT m.name FROM vec_{space} v JOIN mem m ON m.rowid = v.rowid "
+                "WHERE v.emb MATCH ? AND k = ? ORDER BY distance",
+                (_pack(qvec), k),
+            ).fetchall()
+            rankings.append((weight, [r[0] for r in rows]))
+
+        rankings.append((FTS_WEIGHT, self._fts_names(query, k)))
+
+        scores: dict[str, float] = {}
+        for weight, ranking in rankings:
+            for rank, name in enumerate(ranking):
+                scores[name] = scores.get(name, 0.0) + weight / (RRF_K + rank)
+
+        out: list[tuple[Memory, float]] = []
+        for name, score in sorted(scores.items(), key=lambda kv: -kv[1])[:k]:
+            mem = self.store.get(name)
+            if mem is not None and mem.status == "active":
+                out.append((mem, score))
+        return out
+
+
+def search_sync(index: MemoryIndex, query: str, k: int = 5) -> list[tuple[Memory, float]]:
+    return asyncio.run(index.search(query, k))
+
+
+def reindex_sync(index: MemoryIndex, force: bool = False) -> tuple[int, int, int]:
+    return asyncio.run(index.reindex(force=force))

rockycode/memory/store.py

@@ -0,0 +1,331 @@
+"""Memory M0: plain markdown files, progressive disclosure, archive-not-delete.
+
+Design: docs/memory-dream.md. The two rules that matter:
+
+1. Markdown is the source of truth. One memory per file under
+   .rockycode/memory/<type-dir>/, lenient `key: value` frontmatter (no YAML
+   dependency, same parser style as skills.py). The user can read, edit,
+   git-track, or delete any memory with normal tools; future indexes
+   (sqlite-vec, M1) are rebuildable caches, never canonical.
+2. Nothing is ever hard-deleted by rockycode. `rm` moves the file to
+   archive/ with status flipped — wrong memories go away, but stay
+   auditable.
+
+Loading mirrors the skills pattern: MEMORY.md (the hand-curated index) and
+`feedback` memories load fully into the system prompt; everything else gets
+a one-line index entry and is fetched on demand via the `recall_memory`
+tool. Fifty memories cost fifty lines, not fifty files.
+
+Chat-only, like skills and MCP: bench never loads memory — cross-task
+memory contaminates SWE-bench scores (see design doc §4).
+"""
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from rockycode.engine.tools import Tool, _truncate
+
+MEMORY_DIR = Path(".rockycode") / "memory"
+INDEX_FILE = "MEMORY.md"
+
+TYPE_DIRS = {
+    "fact": "facts", "skill": "skills", "episode": "episodes",
+    "feedback": "feedback", "weakness": "weaknesses",
+}
+ARCHIVE_DIR = "archive"
+
+MAX_INDEX_CHARS = 8_000        # MEMORY.md cap in the system prompt
+MAX_FEEDBACK_CHARS = 1_000     # per feedback memory in the system prompt
+MAX_DESCRIPTION_CHARS = 150
+
+_FRONTMATTER = re.compile(r"\A---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+_LIST_FIELDS = {"evidence", "triggers"}
+
+
+@dataclass
+class Memory:
+    name: str
+    type: str = "fact"             # fact | skill | episode | feedback | weakness
+    description: str = ""          # one-liner shown in the index
+    importance: int = 5            # 1–10
+    status: str = "active"         # active | archived
+    origin: str = "user"           # user | agent | dream
+    created: str = ""              # YYYY-MM-DD
+    evidence: list[str] = field(default_factory=list)   # trajectory session ids
+    triggers: list[str] = field(default_factory=list)   # globs/keywords (used from M1)
+    body: str = ""
+    path: Optional[Path] = None
+
+
+def _slugify(text: str, max_len: int = 48) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return slug[:max_len].rstrip("-") or "memory"
+
+
+def _parse_list(value: str) -> list[str]:
+    inner = value.strip().strip("[]")
+    return [v.strip().strip("'\"") for v in inner.split(",") if v.strip().strip("'\"")]
+
+
+def parse_memory(text: str, path: Optional[Path] = None) -> Memory:
+    """Lenient parse; a file with no frontmatter is still a valid memory."""
+    m = _FRONTMATTER.match(text)
+    fields: dict[str, str] = {}
+    body = text
+    if m:
+        for line in m.group(1).splitlines():
+            if ":" in line and not line.startswith((" ", "\t", "#")):
+                key, _, value = line.partition(":")
+                fields[key.strip().lower()] = value.strip()
+        body = text[m.end():]
+    body = body.strip()
+
+    def clean(key: str, default: str = "") -> str:
+        return fields.get(key, default).strip("'\"")
+
+    try:
+        importance = max(1, min(10, int(clean("importance", "5"))))
+    except ValueError:
+        importance = 5
+
+    first_line = body.splitlines()[0].strip() if body else ""
+    return Memory(
+        name=clean("name") or (path.stem if path else _slugify(first_line)),
+        type=clean("type") if clean("type") in TYPE_DIRS else "fact",
+        description=(clean("description") or first_line)[:MAX_DESCRIPTION_CHARS],
+        importance=importance,
+        status=clean("status") or "active",
+        origin=clean("origin") or "user",
+        created=clean("created"),
+        evidence=_parse_list(fields.get("evidence", "")),
+        triggers=_parse_list(fields.get("triggers", "")),
+        body=body,
+        path=path,
+    )
+
+
+def to_markdown(mem: Memory) -> str:
+    lines = [
+        "---",
+        f"name: {mem.name}",
+        f"type: {mem.type}",
+        f"description: {mem.description}",
+        f"importance: {mem.importance}",
+        f"status: {mem.status}",
+        f"origin: {mem.origin}",
+        f"created: {mem.created}",
+        f"evidence: [{', '.join(mem.evidence)}]",
+        f"triggers: [{', '.join(mem.triggers)}]",
+        "---",
+        "",
+        mem.body.strip(),
+        "",
+    ]
+    return "\n".join(lines)
+
+
+class MemoryStore:
+    """All paths relative to one root: <workdir>/.rockycode/memory."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    @classmethod
+    def for_workdir(cls, workdir: Path) -> "MemoryStore":
+        return cls(workdir / MEMORY_DIR)
+
+    def index_text(self) -> str:
+        p = self.root / INDEX_FILE
+        try:
+            return p.read_text(encoding="utf-8", errors="replace") if p.exists() else ""
+        except OSError:
+            return ""
+
+    def load_all(self, include_archived: bool = False) -> list[Memory]:
+        out: list[Memory] = []
+        dirs = list(TYPE_DIRS.values()) + ([ARCHIVE_DIR] if include_archived else [])
+        for d in dirs:
+            folder = self.root / d
+            if not folder.is_dir():
+                continue
+            for f in sorted(folder.glob("*.md")):
+                try:
+                    mem = parse_memory(f.read_text(encoding="utf-8", errors="replace"), path=f)
+                except OSError:
+                    continue
+                if d == ARCHIVE_DIR:
+                    mem.status = "archived"
+                out.append(mem)
+        return out
+
+    def get(self, name: str) -> Optional[Memory]:
+        for mem in self.load_all(include_archived=True):
+            if mem.name == name:
+                return mem
+        return None
+
+    def save(self, mem: Memory) -> Path:
+        if not mem.created:
+            mem.created = time.strftime("%Y-%m-%d")
+        if not mem.name:
+            mem.name = _slugify(mem.description or mem.body)
+        folder = self.root / TYPE_DIRS.get(mem.type, "facts")
+        folder.mkdir(parents=True, exist_ok=True)
+        path = folder / f"{_slugify(mem.name)}.md"
+        if path.exists() and (mem.path is None or path != mem.path):
+            path = folder / f"{_slugify(mem.name)}-{time.strftime('%H%M%S')}.md"
+        path.write_text(to_markdown(mem), encoding="utf-8")
+        mem.path = path
+        return path
+
+    def archive(self, name: str) -> bool:
+        """Move a memory to archive/ — never delete. Returns False if absent."""
+        mem = self.get(name)
+        if mem is None or mem.path is None or mem.status == "archived":
+            return False
+        mem.status = "archived"
+        archive = self.root / ARCHIVE_DIR
+        archive.mkdir(parents=True, exist_ok=True)
+        target = archive / mem.path.name
+        if target.exists():
+            target = archive / f"{mem.path.stem}-{time.strftime('%H%M%S')}.md"
+        target.write_text(to_markdown(mem), encoding="utf-8")
+        mem.path.unlink()
+        return True
+
+    def search(self, query: str) -> list[Memory]:
+        """M0: case-insensitive substring over name/description/body.
+        M1 replaces this with hybrid sqlite-vec + FTS search."""
+        q = query.lower()
+        return [
+            m for m in self.load_all()
+            if q in m.name.lower() or q in m.description.lower() or q in m.body.lower()
+        ]
+
+
+# ---- system prompt + tools ---------------------------------------------------
+
+def memory_prompt_section(store: MemoryStore) -> str:
+    """MEMORY.md + feedback fully; everything else as index lines."""
+    parts: list[str] = []
+
+    index = store.index_text().strip()
+    if index:
+        parts.append(f"# Project memory (MEMORY.md)\n\n{index[:MAX_INDEX_CHARS]}")
+
+    memories = [m for m in store.load_all() if m.status == "active"]
+    feedback = [m for m in memories if m.type == "feedback"]
+    others = [m for m in memories if m.type != "feedback"]
+
+    if feedback:
+        notes = "\n\n".join(f"- {m.body[:MAX_FEEDBACK_CHARS]}" for m in feedback)
+        parts.append(f"# User feedback (always follow)\n\n{notes}")
+
+    if others:
+        lines = [f"- {m.name} [{m.type}] — {m.description}" for m in others]
+        parts.append(
+            "# Memories available\n\n"
+            "Knowledge from past sessions. When one looks relevant, call the "
+            "`recall_memory` tool with its name — or a free-text `query` to "
+            "search by meaning — before relying on it.\n\n"
+            + "\n".join(lines)
+        )
+
+    if not parts:
+        return ""
+    return "\n\n" + "\n\n".join(parts)
+
+
+def build_memory_tools(store: MemoryStore, index=None) -> list[Tool]:
+    """`index` is a memory.index.MemoryIndex for semantic recall (M1);
+    None keeps the M0 exact-name behavior with substring fallback."""
+    recall_schema = {
+        "type": "function",
+        "function": {
+            "name": "recall_memory",
+            "description": (
+                "Look up memories. Pass `name` for an exact entry from the "
+                "'Memories available' list, or `query` to search by meaning "
+                "(English or Chinese). Call this before relying on a memory."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string", "description": "Exact memory name from the index."},
+                    "query": {"type": "string", "description": "Free-text search when no exact name is known."},
+                },
+                "required": [],
+            },
+        },
+    }
+
+    def _render(mem: Memory) -> str:
+        note = " (archived — may be outdated or superseded)" if mem.status == "archived" else ""
+        return f"# memory: {mem.name} [{mem.type}]{note}\n\n{mem.body}"
+
+    async def recall(name: str = "", query: str = "") -> str:
+        if name:
+            mem = store.get(name)
+            if mem is None:
+                available = ", ".join(m.name for m in store.load_all()) or "(none)"
+                return f"[error] no memory named '{name}'. available: {available}"
+            return _truncate(_render(mem))
+        if not query:
+            return "[error] pass either name or query"
+        hits: list[Memory] = []
+        if index is not None:
+            try:
+                hits = [m for m, _ in await index.search(query, k=3)]
+            except Exception:  # noqa: BLE001 — semantic search is best-effort
+                hits = []
+        if not hits:
+            hits = store.search(query)[:3]
+        if not hits:
+            return f"[error] nothing in memory matches '{query}'"
+        return _truncate("\n\n---\n\n".join(_render(m) for m in hits))
+
+    remember_schema = {
+        "type": "function",
+        "function": {
+            "name": "remember",
+            "description": (
+                "Save a memory for future sessions: a project fact, a verified how-to, "
+                "or user feedback. Keep it one focused fact per call."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string", "description": "Short kebab-case identifier."},
+                    "content": {"type": "string", "description": "The memory body (markdown)."},
+                    "type": {
+                        "type": "string",
+                        "enum": sorted(TYPE_DIRS),
+                        "description": "fact (project knowledge), skill (verified how-to), "
+                        "episode (what happened), feedback (user guidance).",
+                    },
+                    "description": {"type": "string", "description": "One-line summary for the index."},
+                },
+                "required": ["name", "content", "type"],
+            },
+        },
+    }
+
+    async def remember(name: str, content: str, type: str, description: str = "") -> str:
+        mem = Memory(
+            name=name,
+            type=type if type in TYPE_DIRS else "fact",
+            description=description or content.splitlines()[0][:MAX_DESCRIPTION_CHARS],
+            body=content,
+            origin="agent",
+        )
+        path = store.save(mem)
+        return f"[ok] remembered '{mem.name}' ({mem.type}) at {path}"
+
+    return [
+        Tool(name="recall_memory", schema=recall_schema, fn=recall, risk="safe"),
+        Tool(name="remember", schema=remember_schema, fn=remember, risk="moderate"),
+    ]

rockycode/modes/learn/learn.md

@@ -0,0 +1,46 @@
+---
+name: learn
+description: tutor posture — teach the user a paper, a codebase, or a concept
+---
+
+For sessions where the goal is the user's understanding, not an output. The
+material can be anything — a paper, an unfamiliar git repo, a concept. Rocky
+teaches; the user absorbs at their own pace.
+
+# How you hold this session
+
+You are a patient tutor, not a lecturer. The goal is not to look decisive or
+cover everything — it is to keep the material navigable and let understanding
+grow at the right speed. Sit in uncertainty with the user without forcing
+closure.
+
+## The cadence
+
+Small steps. Start from what the user already knows — ask if you don't know.
+Explain one idea, then check: a short question, or "does this connect to what
+you expected?" before moving on. Never answer a confusion with a wall of
+text; shrink the step instead. When the user's framing differs from yours,
+work inside THEIR framing first.
+
+## Learning a codebase
+
+Walk the repo, don't describe it from memory: `read_file` the actual files,
+quote the actual lines, and always give file paths (they render clickable —
+the user can jump in and look). Trace one real path end to end — an entry
+point, a request, one feature's flow — before generalizing about
+architecture. Diagrams that help can become an artifact (`create_artifact`).
+
+## Learning a paper or concept
+
+Build up from the user's current picture; anchor every abstraction in one
+concrete example before naming it. Distinguish "this is in the text" from
+"this is my explanation" — the user should always know which they are
+holding. If a converted markdown of a paper exists (or a conversion skill is
+installed), work from that text so you can quote it exactly.
+
+## Evidence and honesty
+
+Label observation, interpretation, and speculation as such. "I don't know —
+let's check" is a fully valid teaching move, and checking together (a quick
+`web_search`, opening the file) models the skill being taught. No retroactive
+certainty; no pretending the lesson plan was always the plan.

rockycode/modes/research/deep-research.md

@@ -0,0 +1,53 @@
+---
+name: deep-research
+description: survey a topic — scope first, collect broadly, describe papers neutrally
+---
+
+For surveying a research area before forming an argument: a literature review,
+a scoping pass, checking what primary evidence actually exists. The output is
+an evidence map, not a conclusion.
+
+# How you hold this session
+
+This is careful library work, not an argument trying to finish itself early.
+You are a patient research assistant: accurate, restrained, and consistent —
+never impressive-sounding at the cost of being wrong about a paper.
+
+## Scope before anything
+
+Before the collection grows, align three things with the user and keep them
+visible: what question the review collects around, what boundaries are fixed
+for this round, and what output this pass should produce. Scope changes are
+allowed but must be said out loud — never let "KV-cache quantization" silently
+become "everything about long-context inference".
+
+## Collecting
+
+Use `web_research` to fan independent queries out in parallel, then `web_fetch`
+to close-read the sources that matter. For recency-sensitive queries, put the
+current year (from the "Today is" line) into the query itself — "X update
+2026", never "X recent update"; your training prior will otherwise reach for
+an older year. Coverage means covering the chosen
+slice well, not the whole field. Track what is still missing as explicitly as
+what was found — holes in the evidence map are findings too.
+
+## Describing papers
+
+Stay close to what each paper is: title, authors, year, venue/status, and what
+it actually studies or does. If you cannot describe a paper's content reliably,
+say so — never fill the gap with plausible-sounding speculation. Resist early
+labels like "core", "strong evidence", or "relevant": those are already acts
+of analysis, and analysis comes only after the collection is stable and only
+if the user asks for it.
+
+## Keep three layers separate
+
+What was directly observed (a quote, a result, a number from the paper); what
+you interpret it to mean; and what is speculation. Label the second and third.
+A review that mixes these layers cannot be audited later.
+
+## Organizing
+
+Group papers by a simple content axis — topic, method family, task setting.
+Simple classification beats elaborate structure. For a big map, offer a
+markdown table or an artifact (`create_artifact`) the user can keep.