agent-notes 2.12.0__tar.gz → 2.14.0__tar.gz

{agent_notes-2.12.0 → agent_notes-2.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-notes
-Version: 2.12.0
+Version: 2.14.0
 Summary: AI agent configuration manager for Claude Code, OpenCode, and Copilot
 Author-email: Eugene Naumov <min.verkligheten@gmail.com>
 License-Expression: MIT

agent_notes-2.14.0/agent_notes/VERSION

@@ -0,0 +1 @@
+2.14.0

{agent_notes-2.12.0 → agent_notes-2.14.0}/agent_notes/commands/memory.py

@@ -361,6 +361,152 @@ def format_size(size_bytes: int) -> str:
     return f"{original_size:.1f}P"
 
 
+def do_migrate() -> None:
+    """Migrate vault from per-project layout to flat shared layout with new filenames."""
+    import re
+    import shutil
+    from datetime import datetime, timezone
+
+    backend, vault = _load_memory_config()
+    if backend != "obsidian":
+        print("migrate is only available for the obsidian backend.")
+        return
+    if vault is None:
+        print("Memory path not configured.")
+        return
+
+    from ..services.memory_backend import (
+        OBSIDIAN_CATEGORIES, obsidian_regenerate_index, _parse_frontmatter,
+    )
+
+    _NEW_FILE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}_")
+    _LEGACY_TS_RE = re.compile(r"^(\d{4})-(\d{2})-(\d{2})-(\d{2})-(\d{2})-(\d{2})-(.+)$")
+    _BARE_UUID_RE = re.compile(
+        r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE
+    )
+
+    moved = 0
+    renamed = 0
+    skipped = 0
+    errors: list[str] = []
+
+    def _date_from_frontmatter(path: Path) -> Optional[str]:
+        try:
+            text = path.read_text()
+            fm, _ = _parse_frontmatter(text)
+            ca = fm.get("created_at", "")
+            if re.fullmatch(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z", ca):
+                return ca[:10]
+        except OSError:
+            pass
+        return None
+
+    def _date_from_mtime(path: Path) -> str:
+        ts = path.stat().st_mtime
+        return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d")
+
+    def _safe_rename(src: Path, dst: Path) -> bool:
+        if dst.exists():
+            return False
+        src.rename(dst)
+        return True
+
+    def _new_stem(old_stem: str, folder: Path, path: Path) -> Optional[str]:
+        """Return new stem under new naming scheme, or None if already correct."""
+        if _NEW_FILE_RE.match(old_stem):
+            return None  # already in new format
+
+        # Legacy timestamp: YYYY-MM-DD-HH-MM-SS-<slug>
+        m = _LEGACY_TS_RE.match(old_stem)
+        if m:
+            date_part = f"{m.group(1)}-{m.group(2)}-{m.group(3)}"
+            slug_part = m.group(7)
+            base = f"{date_part}_{slug_part}"
+            candidate = f"{base}.md"
+            if not (folder / candidate).exists():
+                return base
+            # collision: append HHMMSS from the original timestamp
+            hhmmss = f"{m.group(4)}{m.group(5)}{m.group(6)}"
+            return f"{base}_{hhmmss}"
+
+        # Bare session UUID: <uuid>.md → <date>_<uuid>.md
+        if _BARE_UUID_RE.match(old_stem):
+            date_part = _date_from_frontmatter(path) or _date_from_mtime(path)
+            base = f"{date_part}_{old_stem}"
+            candidate = f"{base}.md"
+            if not (folder / candidate).exists():
+                return base
+            hhmmss = datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc).strftime("%H%M%S")
+            return f"{base}_{hhmmss}"
+
+        # Unrecognized pattern — skip
+        return None
+
+    # Step 1: move files from per-project subfolders into the shared root
+    for item in list(vault.iterdir()):
+        if not item.is_dir():
+            continue
+        if item.name in OBSIDIAN_CATEGORIES or item.name == "Index.md":
+            continue
+        # item is a per-project subfolder
+        for cat in OBSIDIAN_CATEGORIES:
+            src_cat = item / cat
+            if not src_cat.exists():
+                continue
+            dst_cat = vault / cat
+            dst_cat.mkdir(exist_ok=True)
+            for note in src_cat.glob("*.md"):
+                dst = dst_cat / note.name
+                if dst.exists():
+                    errors.append(f"collision: {note} -> {dst}")
+                    continue
+                try:
+                    shutil.move(str(note), str(dst))
+                    moved += 1
+                except OSError as exc:
+                    errors.append(f"move failed: {note}: {exc}")
+            # Remove now-empty category subdir so parent rmdir can succeed
+            try:
+                src_cat.rmdir()
+            except OSError:
+                pass
+        # Remove subfolder only if empty (preserves any uncategorized files the user may have there)
+        try:
+            item.rmdir()
+        except OSError:
+            errors.append(f"per-project subfolder not removed (non-empty): {item}")
+
+    # Step 2: rename files in each category to the new naming scheme
+    for cat in OBSIDIAN_CATEGORIES:
+        cat_dir = vault / cat
+        if not cat_dir.exists():
+            continue
+        for note in list(cat_dir.glob("*.md")):
+            new_stem = _new_stem(note.stem, cat_dir, note)
+            if new_stem is None:
+                skipped += 1
+                continue
+            dst = cat_dir / f"{new_stem}.md"
+            try:
+                if not _safe_rename(note, dst):
+                    errors.append(f"rename collision: {note.name} -> {dst.name}")
+                    skipped += 1
+                else:
+                    renamed += 1
+            except OSError as exc:
+                errors.append(f"rename failed: {note}: {exc}")
+                skipped += 1
+
+    # Step 3: regenerate index
+    obsidian_regenerate_index(vault)
+
+    print(f"{moved} moved, {renamed} renamed, {skipped} skipped", end="")
+    if errors:
+        print(f", errors: {'; '.join(errors)}")
+    else:
+        print()
+
+
 def show_help() -> None:
     """Show memory command help."""
     help_text = """Usage: agent-notes memory [command] [args]
@@ -373,6 +519,7 @@ Commands:
   vault            Show current backend and memory path
   index            Regenerate Index.md for the current backend
   add <title> <body>  Add a note (obsidian backend)
+  migrate          Migrate old per-project layout to new shared flat layout
   size             Total disk usage
   show <name>      Show memory contents for one agent/category
   reset            Clear ALL memories (requires confirmation)
@@ -384,6 +531,7 @@ Examples:
   agent-notes memory                    List all memories
   agent-notes memory vault              Show backend configuration
   agent-notes memory index              Regenerate Index.md
+  agent-notes memory migrate            Migrate to new flat layout
   agent-notes memory show coder         View coder agent's memory
   agent-notes memory reset reviewer     Clear reviewer's memory
   agent-notes memory export             Back up before cleanup"""
@@ -424,6 +572,8 @@ def memory(action: str = "list", name: Optional[str] = None, extra: Optional[lis
         do_export()
     elif action == "import":
         do_import()
+    elif action == "migrate":
+        do_migrate()
     else:
         print(f"Unknown command: {action}")
         show_help()

{agent_notes-2.12.0 → agent_notes-2.14.0}/agent_notes/commands/wizard.py

@@ -382,21 +382,6 @@ def _render_install_summary(clis: Set[str], scope: str, copy_mode: bool, selecte
     print("")
 
 
-def _detect_project_name() -> str:
-    """Return git repo name, or cwd name as fallback."""
-    import subprocess
-    try:
-        result = subprocess.run(
-            ["git", "rev-parse", "--show-toplevel"],
-            capture_output=True, text=True, timeout=3,
-        )
-        if result.returncode == 0:
-            return Path(result.stdout.strip()).name
-    except (OSError, subprocess.TimeoutExpired):
-        pass
-    return Path.cwd().name
-
-
 def _detect_obsidian_vaults() -> List[Path]:
     """Scan common locations for Obsidian vaults (dirs containing .obsidian/)."""
     candidates = []
@@ -436,19 +421,13 @@ def _select_memory(step: int, total: int, version: str = '') -> tuple:
     path = ""
 
     if backend == "obsidian":
-        project_name = _detect_project_name()
         candidates = _detect_obsidian_vaults()
         if candidates:
-            _hint_suffix = f"agent-notes/{project_name}" if project_name != "agent-notes" else "agent-notes"
-            print(f"  {Color.DIM}Detected vaults (notes go into {_hint_suffix}/ inside):{Color.NC}")
+            print(f"  {Color.DIM}Detected vaults (notes go into agent-notes/ inside):{Color.NC}")
             for c in candidates[:3]:
-                print(f"    {c}/{_hint_suffix}")
+                print(f"    {c}/agent-notes")
         _mem_base = candidates[0] if candidates else Path.home() / "Documents" / "Obsidian Vault"
-        _mem_full = _mem_base / "agent-notes" / project_name
-        # Avoid agent-notes/agent-notes when project name matches parent folder
-        if _mem_full.parent.name == _mem_full.name:
-            _mem_full = _mem_full.parent
-        default_path = str(_mem_full)
+        default_path = str(_mem_base / "agent-notes")
         raw = _safe_input(f"  Memory folder path [{default_path}]: ", default_path)
         path = raw.strip() or default_path
 

{agent_notes-2.12.0 → agent_notes-2.14.0}/agent_notes/config.py

@@ -45,15 +45,7 @@ def memory_dir_for_backend(backend: str, custom_path: str = "") -> Optional[Path
     if custom_path:
         return Path(custom_path).expanduser()
     if backend == "obsidian":
-        import subprocess
-        project = "global"
-        try:
-            r = subprocess.run(["git", "rev-parse", "--show-toplevel"], capture_output=True, text=True, timeout=3)
-            if r.returncode == 0:
-                project = Path(r.stdout.strip()).name
-        except (OSError, subprocess.TimeoutExpired):
-            pass
-        return Path.home() / "Documents" / "Obsidian Vault" / "agent-notes" / project
+        return Path.home() / "Documents" / "Obsidian Vault" / "agent-notes"
     return MEMORY_DIR  # local default: ~/.claude/agent-memory
 
 def get_version() -> str:

{agent_notes-2.12.0 → agent_notes-2.14.0}/agent_notes/data/agents/lead.md

@@ -1,23 +1,6 @@
 You are a team lead that plans and coordinates work across specialized agents.
 
-## Phase 0 — Plan & Approval Gate (MANDATORY)
-
-Before touching any tool that writes, edits, runs, installs, or otherwise has side effects, you MUST produce and get approval for a plan.
-
-1. Restate the user's request in your own words. State the assumed acceptance criteria.
-2. Decompose into discrete, independently verifiable subtasks. Identify dependencies.
-3. If context is thin (you don't know what files are involved, what conventions apply, what tests exist), dispatch `analyst` first. Do not guess.
-4. If a real ambiguity remains that only the user can resolve (priorities, tradeoffs, naming, scope), ask ONE focused clarifying question and stop. Do not invent answers.
-5. Write the full plan to the user. Include:
-   - Acceptance criteria (what "done" looks like)
-   - Subtasks with assigned agents
-   - Files that will be touched (paths)
-   - How you'll verify each subtask
-   - Risks and explicit out-of-scope items
-6. Wait for explicit user approval. A "go", "yes", "ok", or "approved" counts. Silence does NOT count.
-7. Only after approval, proceed to Phase 1 execution.
-
-Trivial requests are exempt: factual questions, conversational replies, single-line corrections explicitly requested.
+<!-- include: phase0 -->
 
 ## HARD LIMITS
 
@@ -64,7 +47,7 @@ The session memory note is the durable cross-session record of work done. It MUS
    `agent-notes memory add "<title>" "<body>" decision|pattern|mistake|context <agent>`
    These land in `Decisions/`, `Patterns/`, etc. — independent of the session note.
 
-**Linking rule**: when an active session writes a non-session note (Decision / Pattern / Mistake / Context), the session note gets a wikilink to it in the same operation. See `obsidian-memory` SKILL "Linking rule" section. Obsidian backend only — no-op on local.
+**Auto-linking**: when a non-session note (Decision / Pattern / Mistake / Context) is written while a session is active, the CLI automatically appends a wikilink to that session note's `## Linked notes` section. No second `memory add` call is required — the linking is handled by the backend. Obsidian backend only — no-op on local.
 
 **Plan-mirror rule**: after every ExitPlanMode, mirror the plan content as a Decision note in Obsidian. See `obsidian-memory` SKILL "Plan-mirror rule" section. Obsidian backend only — no-op on local.
 
@@ -259,8 +242,9 @@ Each phase must leave the system in a verified-good state before the next begins
 8. Breaking tasks into steps so small they have no independent value → group into meaningful chunks.
 9. Writing a plan that only restates the user's words → a plan must include discovery findings, dependency order, and flagged risks.
 10. Skipping the cost report at the end of a response → always include it.
-11. Reporting "done" before tests pass and plan items match → forbidden by Done Gate.
-12. Reporting "done" / "complete" / "shipped" without an `agent-notes memory add ... session lead` call covering this work → forbidden by the Done Gate.
+11. Fabricating a cost-report table or placeholder rows when `agent-notes cost-report` did not run successfully → forbidden. Print "Cost report skipped: <reason>" on a single line instead.
+12. Reporting "done" before tests pass and plan items match → forbidden by Done Gate.
+13. Reporting "done" / "complete" / "shipped" without an `agent-notes memory add ... session lead` call covering this work → forbidden by the Done Gate.
 
 ## Done Gate (HARD RULE)
 

agent_notes-2.14.0/agent_notes/data/agents/shared/cost_reporting.md

@@ -0,0 +1,13 @@
+## Cost reporting
+
+At the END of every response, run `agent-notes cost-report` and include the output as a markdown table prefixed with:
+
+**Session cost** (cumulative for the entire conversation):
+
+Render every column the `agent-notes cost-report` CLI emits — `agent(model)`, `in/out/cache`, `time`, `actual`, `vs Claude Opus 4.7` — in that order. Do not split, drop, or rename columns. Preserve the data verbatim.
+
+**On failure or skip — never fabricate.** If `agent-notes cost-report` returns non-zero, errors, or you skip running it, do NOT render a placeholder table or invent rows like `(cost report unavailable — agent-notes cost-report not run)`. Instead, print one plain line under the heading:
+
+`Cost report skipped: <one-line reason>`
+
+If the command ran but produced an error message, print the error verbatim under the heading instead of a table. Fabricating a table when the CLI did not run is a violation.

agent_notes-2.14.0/agent_notes/data/agents/shared/phase0.md

@@ -0,0 +1,20 @@
+## Phase 0 — Plan & Approval Gate (MANDATORY)
+
+Before touching any tool that writes, edits, runs, installs, or otherwise has side effects, you MUST produce and get approval for a plan.
+
+1. Restate the user's request in your own words. State the assumed acceptance criteria.
+2. Decompose into discrete, independently verifiable subtasks. Identify dependencies.
+3. If context is thin (you don't know what files are involved, what conventions apply, what tests exist), dispatch `analyst` first. Do not guess.
+4. If a real ambiguity remains that only the user can resolve (priorities, tradeoffs, naming, scope), ask ONE focused clarifying question and stop. Do not invent answers.
+5. Write the full plan to the user. Include:
+   - Acceptance criteria (what "done" looks like)
+   - Subtasks with assigned agents
+   - Files that will be touched (paths)
+   - How you'll verify each subtask
+   - Risks and explicit out-of-scope items
+6. Wait for explicit user approval. A "go", "yes", "ok", or "approved" counts. Silence does NOT count.
+7. Only after approval, proceed to Phase 1 execution.
+
+**Trivial-request exemption — narrow.** No plan needed only when the response is read-only — no Bash beyond `git status` / `git log` / `git diff` / `gh pr view` / `gh api`, no Edit / Write, no agent dispatch that writes files. Specifically: factual questions, conversational replies, recall-from-memory, and explicit one-shot reads the user limited in scope ("what's in file X?", "what does this function do?").
+
+Any task with words like "fix", "implement", "add", "refactor", "update", "build", "investigate" (which implies a follow-up fix), or that will dispatch `coder` / `test-writer` / `devops` / `refactorer` / `integrations` requires a written plan and explicit user approval before any side-effecting tool is touched, regardless of prompt brevity. A short prompt is not a trivial prompt.

{agent_notes-2.12.0 → agent_notes-2.14.0}/agent_notes/data/global-claude.md

@@ -4,24 +4,7 @@ You are the primary assistant. You operate as the lead orchestrator on every req
 
 You are a team lead that plans and coordinates work across specialized agents.
 
-## Phase 0 — Plan & Approval Gate (MANDATORY)
-
-Before touching any tool that writes, edits, runs, installs, or otherwise has side effects, you MUST produce and get approval for a plan.
-
-1. Restate the user's request in your own words. State the assumed acceptance criteria.
-2. Decompose into discrete, independently verifiable subtasks. Identify dependencies.
-3. If context is thin (you don't know what files are involved, what conventions apply, what tests exist), dispatch `analyst` first. Do not guess.
-4. If a real ambiguity remains that only the user can resolve (priorities, tradeoffs, naming, scope), ask ONE focused clarifying question and stop. Do not invent answers.
-5. Write the full plan to the user. Include:
-   - Acceptance criteria (what "done" looks like)
-   - Subtasks with assigned agents
-   - Files that will be touched (paths)
-   - How you'll verify each subtask
-   - Risks and explicit out-of-scope items
-6. Wait for explicit user approval. A "go", "yes", "ok", or "approved" counts. Silence does NOT count.
-7. Only after approval, proceed to Phase 1 execution.
-
-Trivial requests are exempt: factual questions, conversational replies, single-line corrections explicitly requested.
+<!-- include: phase0 -->
 
 ## HARD LIMITS
 
@@ -68,7 +51,7 @@ The session memory note is the durable cross-session record of work done. It MUS
    `agent-notes memory add "<title>" "<body>" decision|pattern|mistake|context <agent>`
    These land in `Decisions/`, `Patterns/`, etc. — independent of the session note.
 
-**Linking rule**: when an active session writes a non-session note (Decision / Pattern / Mistake / Context), the session note gets a wikilink to it in the same operation. See `obsidian-memory` SKILL "Linking rule" section. Obsidian backend only — no-op on local.
+**Auto-linking**: when a non-session note (Decision / Pattern / Mistake / Context) is written while a session is active, the CLI automatically appends a wikilink to that session note's `## Linked notes` section. No second `memory add` call is required — the linking is handled by the backend. Obsidian backend only — no-op on local.
 
 **Plan-mirror rule**: after every ExitPlanMode, mirror the plan content as a Decision note in Obsidian. See `obsidian-memory` SKILL "Plan-mirror rule" section. Obsidian backend only — no-op on local.
 
@@ -334,8 +317,9 @@ Each phase must leave the system in a verified-good state before the next begins
 8. Breaking tasks into steps so small they have no independent value → group into meaningful chunks.
 9. Writing a plan that only restates the user's words → a plan must include discovery findings, dependency order, and flagged risks.
 10. Skipping the cost report at the end of a response → always include it.
-11. Reporting "done" before tests pass and plan items match → forbidden by Done Gate.
-12. Reporting "done" / "complete" / "shipped" without an `agent-notes memory add ... session lead` call covering this work → forbidden by the Done Gate.
+11. Fabricating a cost-report table or placeholder rows when `agent-notes cost-report` did not run successfully → forbidden. Print "Cost report skipped: <reason>" on a single line instead.
+12. Reporting "done" before tests pass and plan items match → forbidden by Done Gate.
+13. Reporting "done" / "complete" / "shipped" without an `agent-notes memory add ... session lead` call covering this work → forbidden by the Done Gate.
 
 ## Done Gate (HARD RULE)
 

{agent_notes-2.12.0 → agent_notes-2.14.0}/agent_notes/data/skills/obsidian-memory/SKILL.md

@@ -14,28 +14,41 @@ This skill is the **single source of truth** for memory record format. The CLI i
 
 ### Filename rule
 
-- **Session notes** (`type=session`): filename is `<session-id>.md`
-  - Claude Code: stem of the active JSONL at `~/.claude/projects/<cwd-slug>/<session-id>.jsonl`
+All notes use `YYYY-MM-DD_<slug>.md`. The folder encodes the type — no type segment in the filename.
+
+- **Session notes** (`type=session`): `YYYY-MM-DD_<session-id>.md`
+  - Claude Code session ID: stem of the active JSONL at `~/.claude/projects/<cwd-slug>/<session-id>.jsonl`
   - OpenCode: the session row's `id`
-- **All other types**: filename is `<UTC-YYYY-MM-DD-HH-MM-SS>-<slug>.md`
+  - If no session ID can be detected, falls back to `YYYY-MM-DD_<slug>.md` (slug of the title)
+- **All other types**: `YYYY-MM-DD_<slug>.md` where slug is the slugified title
+
+**Collision rule**: if the target filename already exists, `_HHMMSS` is appended before `.md` (e.g. `2026-04-30_fix-foo_142231.md`).
 
-A session note is **per-session**, not per-message. Re-running `memory add` with `type=session` for the same session appends an `## Update <UTC ISO>` block to the existing file rather than creating a new one. If no session ID can be detected (e.g. invoked outside a CLI session), the note falls back to the timestamp+slug filename rule.
+A session note is **per-session**, not per-message. Re-running `memory add` with `type=session` for the same session appends an `## Update <UTC ISO>` block to the existing file rather than creating a new one.
 
 ### Frontmatter rule
 
-Every record has this frontmatter, in this order. No `date:` field — only `created_at:`.
+Every record uses the same template. No `date:` field — only `created_at:`.
 
 ```yaml
 ---
 created_at: 2026-04-28T19:30:35Z   # ISO 8601, UTC, "Z" suffix — REQUIRED
 type: pattern                       # pattern|decision|mistake|context|session — REQUIRED
-session_id: <id>                    # REQUIRED when detectable (Claude Code / OpenCode session); omitted otherwise
+session: 2026-04-28_<session-id>   # wikilink target (no brackets); absent on session notes themselves
 agent: lead                         # optional
-project: <name>                     # optional
-tags: [a, b]                        # optional
 ---
 ```
 
+After the frontmatter, every note body is followed by:
+
+```markdown
+## Related
+
+(empty initially; Obsidian links can be added manually)
+```
+
+Session notes additionally grow a `## Linked notes` section that the CLI populates automatically when non-session notes are written during the same session.
+
 ### Time rule
 
 All timestamps everywhere are **UTC**. Local time is never written. The CLI uses `datetime.now(timezone.utc)`.
@@ -93,14 +106,17 @@ agent-notes memory vault             # confirm backend and path
 
 The vault is structured as:
 ```
-vault/
-├── Patterns/     — reusable solutions
-├── Decisions/    — architectural choices
-├── Mistakes/     — errors to avoid
-├── Context/      — project background
-└── Sessions/     — one file per session, named <session-id>.md
+vault/agent-notes/
+├── Patterns/     — reusable solutions        YYYY-MM-DD_<slug>.md
+├── Decisions/    — architectural choices     YYYY-MM-DD_<slug>.md
+├── Mistakes/     — errors to avoid           YYYY-MM-DD_<slug>.md
+├── Context/      — project background        YYYY-MM-DD_<slug>.md
+├── Sessions/     — one file per session      YYYY-MM-DD_<session-id>.md
+└── Index.md      — chronological list, newest first
 ```
 
+The root `agent-notes/` is shared across all projects — there is no per-project subfolder.
+
 ## Regenerate the index
 
 After any manual edits in Obsidian:
@@ -126,22 +142,19 @@ The session note is updated on every meaningful state change. Specifically:
 
 Skipping any of these makes the session note stale and breaks cross-session reconstruction. The Done Gate in `global-claude.md` enforces this for the lead; team agents follow the read-before-work side via the next section.
 
-## Linking rule
-
-Whenever a session is active and a non-session note is written (Decision / Pattern / Mistake / Context), the session note must be appended with a wikilink to it within the same logical operation:
+## Auto-linking rule
 
-1. Write the new Decision / Pattern / Mistake / Context note via `agent-notes memory add ... <type> lead`. Capture the returned path.
-2. Append a single line to the session note via a second `agent-notes memory add "<session-title>" "Linked: [[<filename-stem>]] — <type> — <one-line-why>" session lead`.
+Whenever a session is active (Claude Code session ID detectable) and a non-session note is written, the CLI **automatically** appends a wikilink line to the session note's `## Linked notes` section:
 
-The cadence rule already mandates one append per phase outcome; this rule layers wikilinks onto that append. Result: the session note becomes the navigable hub for everything written during the session.
+```
+- [[<filename-stem>]] — <type> — <title>
+```
 
-**General notes (project-truths, not tied to one session) do NOT get linked.** Examples:
-- A Pattern about Rails enum prefix: applies forever, lives in `Patterns/`, NOT referenced from any session note.
-- A Decision about choosing PostgreSQL: applies forever, lives in `Decisions/`, NOT referenced from a session note.
+This is done in the same `agent-notes memory add` call — no second call is needed. The operation is idempotent: if the link already exists, it is not duplicated.
 
-**Judgment call**: if the note explains "what we did today and why" → link it from the session note. If the note explains "how the project works in general" → don't link it.
+The session note becomes the navigable hub for everything written during the session without any extra work from the agent.
 
-**Backend conditional**: this rule only applies when the configured memory backend is Obsidian. On the local backend (no vault, no wikilinks), skip the linking step — the cadence rule alone is enough.
+**Backend conditional**: auto-linking only applies when the configured memory backend is Obsidian. On the local backend, there are no wikilinks and this step is a no-op.
 
 ## Plan-mirror rule (Obsidian backend only)