agent-notes 2.22.0__tar.gz → 2.24.0__tar.gz

{agent_notes-2.22.0 → agent_notes-2.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-notes
-Version: 2.22.0
+Version: 2.24.0
 Summary: AI agent configuration manager for Claude Code, OpenCode, and Copilot
 Author-email: Eugene Naumov <min.verkligheten@gmail.com>
 License-Expression: MIT
@@ -42,7 +42,7 @@ agent-notes doctor
 
 **What's Included**
 - 19 specialized AI subagents (Opus reasons, Sonnet executes, Haiku explores)
-- 42+ on-demand skills (Rails, Docker, Git, Kamal, Process)
+- 47+ on-demand skills (Rails, Docker, Git, Kamal, Process)
 - Global rules and guardrails
 - Agent memory with 3 storage options (Local, Obsidian, Wiki)
 - Configuration for Claude Code, OpenCode, and GitHub Copilot
@@ -267,7 +267,7 @@ Implements Karpathy's LLM Wiki pattern (v1). Auto-creates a folder per project (
 
 - **Query** — Search wiki pages, synthesize answers with citations, optionally file answers back as new pages
 
-- **Lint** — Health-check for contradictions, stale claims, orphan pages, missing cross-references
+- **Lint** — Health-check for contradictions, stale pages, data gaps, orphan pages, missing cross-references
 
 **Commands:**
 ```bash
@@ -312,7 +312,7 @@ The installed `CLAUDE.md` already points agents to your vault. At the start of a
 <details>
 <summary>Skills</summary>
 
-42+ on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
+47+ on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
 
 The session context hook auto-generates a skill index from SKILL.md frontmatter at install time, so agents always know what skills are available without loading full skill content. This keeps context overhead low while maintaining skill discoverability.
 
@@ -342,6 +342,11 @@ Load the docker-compose skill for multi-service setup
 - `/debugging-protocol` — Phase 1 rewritten as "build a feedback loop first" with 9 strategies
 - `/improve-codebase-architecture` — Deletion test to find shallow modules; surfaces deepening opportunities
 - `/zoom-out` — Quick orientation map of an unfamiliar code area
+- `/handoff` — Compact conversation into a handoff document for a fresh agent session
+- `/to-prd` — Synthesize conversation into a Product Requirements Document
+- `/to-issues` — Break a plan/PRD into vertical-slice issues (HITL/AFK classification)
+- `/prototype` — Throwaway prototypes: terminal app for logic or UI variations for visual
+- `/write-a-skill` — Meta-skill for creating new skills with proper structure
 
 </details>
 

{agent_notes-2.22.0 → agent_notes-2.24.0}/README.md

@@ -12,7 +12,7 @@ agent-notes doctor
 
 **What's Included**
 - 19 specialized AI subagents (Opus reasons, Sonnet executes, Haiku explores)
-- 42+ on-demand skills (Rails, Docker, Git, Kamal, Process)
+- 47+ on-demand skills (Rails, Docker, Git, Kamal, Process)
 - Global rules and guardrails
 - Agent memory with 3 storage options (Local, Obsidian, Wiki)
 - Configuration for Claude Code, OpenCode, and GitHub Copilot
@@ -237,7 +237,7 @@ Implements Karpathy's LLM Wiki pattern (v1). Auto-creates a folder per project (
 
 - **Query** — Search wiki pages, synthesize answers with citations, optionally file answers back as new pages
 
-- **Lint** — Health-check for contradictions, stale claims, orphan pages, missing cross-references
+- **Lint** — Health-check for contradictions, stale pages, data gaps, orphan pages, missing cross-references
 
 **Commands:**
 ```bash
@@ -282,7 +282,7 @@ The installed `CLAUDE.md` already points agents to your vault. At the start of a
 <details>
 <summary>Skills</summary>
 
-42+ on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
+47+ on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
 
 The session context hook auto-generates a skill index from SKILL.md frontmatter at install time, so agents always know what skills are available without loading full skill content. This keeps context overhead low while maintaining skill discoverability.
 
@@ -312,6 +312,11 @@ Load the docker-compose skill for multi-service setup
 - `/debugging-protocol` — Phase 1 rewritten as "build a feedback loop first" with 9 strategies
 - `/improve-codebase-architecture` — Deletion test to find shallow modules; surfaces deepening opportunities
 - `/zoom-out` — Quick orientation map of an unfamiliar code area
+- `/handoff` — Compact conversation into a handoff document for a fresh agent session
+- `/to-prd` — Synthesize conversation into a Product Requirements Document
+- `/to-issues` — Break a plan/PRD into vertical-slice issues (HITL/AFK classification)
+- `/prototype` — Throwaway prototypes: terminal app for logic or UI variations for visual
+- `/write-a-skill` — Meta-skill for creating new skills with proper structure
 
 </details>
 

agent_notes-2.24.0/agent_notes/VERSION

@@ -0,0 +1 @@
+2.24.0

{agent_notes-2.22.0 → agent_notes-2.24.0}/agent_notes/cli.py

@@ -275,6 +275,12 @@ def main():
         help="Memory action")
     p_memory.add_argument("name", nargs="?", help="Agent name / note title (for show/reset/add)")
     p_memory.add_argument("extra", nargs="*", help="Additional args (for add: body [type] [agent] [project])")
+    p_memory.add_argument("--description", default="", help="One-liner description for index display")
+
+    # hook
+    p_hook = subparsers.add_parser("hook", help="Claude Code hook integrations")
+    p_hook.add_argument("subaction", choices=["memory-bridge"],
+        help="Hook to run")
 
     # cost-report
     p_cost_report = subparsers.add_parser("cost-report", help="Report token usage and cost for the current AI session")
@@ -284,7 +290,7 @@ def main():
     # config
     p_config = subparsers.add_parser("config", help="Reconfigure role/agent/model/memory/skill assignments after install")
     p_config.add_argument("action", nargs="?", default="wizard",
-        choices=["wizard", "show", "role-model", "role-agent", "provider", "providers"],
+        choices=["wizard", "show", "role-model", "role-agent", "provider", "providers", "memory"],
         help="Config action (default: wizard)")
     p_config.add_argument("extra", nargs="*", help="Additional positional args (role, model, agent)")
     p_config.add_argument("--cli", help="Target CLI (claude / opencode / both)")
@@ -335,10 +341,13 @@ def main():
         regenerate(scope=args.scope, cli=args.cli, local=args.local)
     elif args.command == "memory":
         from .commands.memory import memory
-        memory(args.action, args.name, getattr(args, "extra", None))
+        memory(args.action, args.name, getattr(args, "extra", None), description=getattr(args, "description", ""))
     elif args.command == "config":
         from .commands.config import config
         config(action=args.action, args=getattr(args, "extra", None) or [], cli_filter=args.cli)
+    elif args.command == "hook":
+        from .commands.hook import hook
+        hook(args.subaction)
     elif args.command == "cost-report":
         # Rebuild sys.argv slice so cost_report.main() can parse it normally
         argv = []

{agent_notes-2.22.0 → agent_notes-2.24.0}/agent_notes/commands/build.py

@@ -91,18 +91,18 @@ def count_lines(file_path: Path) -> int:
 
 def build() -> None:
     """Build agent configuration files from source."""
-    from .. import state as state_module
+    from ..services.state_store import load_state
     from ..config import ROOT
-    
+
     # Read configuration
     try:
         agents_config, tiers = load_agents_config()
     except FileNotFoundError as e:
         print(f"Error: {e}")
         return
-    
+
     # Load state if present (no error if missing)
-    state = state_module.load()
+    state = load_state()
     
     # Generate agent files (state=None is backward compatible)
     print("Generating agent files...")

{agent_notes-2.22.0 → agent_notes-2.24.0}/agent_notes/commands/config.py

@@ -7,11 +7,13 @@ import sys
 from pathlib import Path
 from typing import Optional
 
+from ..constants import DEFAULT_VAULT_DIR, DEFAULT_VAULT_NAME, Wiki, Obsidian
+
 
 def _load_state():
     """Load state or exit with a clear message."""
-    from .. import state as state_mod
-    st = state_mod.load()
+    from ..services.state_store import load_state
+    st = load_state()
     if st is None:
         print("No installation found. Run `agent-notes install` first.")
         sys.exit(1)
@@ -95,7 +97,7 @@ def _print_diff(before: str, after: str) -> None:
 
 def _apply_and_regenerate(state, before: str) -> None:
     """Show diff, prompt, then write + regenerate on Y."""
-    from .. import install_state
+    from ..services.state_store import record_install_state
     from ..config import Color
     from ..services.ui import _safe_input
 
@@ -114,7 +116,7 @@ def _apply_and_regenerate(state, before: str) -> None:
         print("Discarded. No changes written.")
         return
 
-    install_state.record_install_state(state)
+    record_install_state(state)
     print("State written.")
 
     # Regenerate
@@ -311,9 +313,9 @@ def _wizard_memory(state, before: str) -> bool:
     from ..services.ui import _safe_input, _path_input
 
     storage_options = {
-        "1": ("local", "Local markdown files (~/.claude/agent-memory/)"),
+        "1": ("local", "Local files"),
         "2": ("obsidian", "Obsidian vault"),
-        "3": ("none", "None (disable memory)"),
+        "3": ("none", "Disabled"),
     }
 
     print("\nMemory storage options:")
@@ -329,7 +331,10 @@ def _wizard_memory(state, before: str) -> bool:
     path = ""
 
     if backend == "obsidian":
-        mode_options = {"1": ("obsidian", "Session-oriented"), "2": ("wiki", "Wiki")}
+        mode_options = {
+            "1": ("obsidian", "Session notes — project-scoped decisions, patterns, mistakes"),
+            "2": ("wiki", "Knowledge wiki — Karpathy compile-once pattern with concepts, entities, sources"),
+        }
         print("\n  Obsidian mode:")
         for key, (_, mlabel) in mode_options.items():
             print(f"    {key}) {mlabel}")
@@ -337,8 +342,8 @@ def _wizard_memory(state, before: str) -> bool:
         if mode_choice in mode_options:
             backend, label = mode_options[mode_choice]
 
-        subfolder = "notes" if backend == "obsidian" else "knowledge"
-        default_vault = str(Path.home() / "Documents" / "Obsidian Vault")
+        subfolder = Obsidian.SUBFOLDER if backend == "obsidian" else Wiki.SUBFOLDER
+        default_vault = str(Path.home() / DEFAULT_VAULT_DIR / DEFAULT_VAULT_NAME)
         print(f"  Folder name: {subfolder}")
         print("  Press Tab to autocomplete paths")
         raw = _path_input(f"  Vault path [{default_vault}]: ", default_vault).strip()
@@ -453,6 +458,13 @@ def interactive_config() -> None:
         print(f"Unknown choice '{choice}'. Quit.")
 
 
+def interactive_config_memory() -> None:
+    """Run the interactive memory config wizard."""
+    state = _load_state()
+    before = _state_snapshot(state)
+    _wizard_memory(state, before)
+
+
 # ── Entry point ──────────────────────────────────────────────────────────────
 
 def config(action: str = "wizard", args: Optional[list] = None, cli_filter: Optional[str] = None) -> None:
@@ -483,7 +495,9 @@ def config(action: str = "wizard", args: Optional[list] = None, cli_filter: Opti
             print("Usage: agent-notes config provider <name>")
             sys.exit(1)
         _wizard_provider_status(args[0])
+    elif action == "memory":
+        interactive_config_memory()
     else:
         print(f"Unknown config action: {action}")
-        print("Actions: wizard, show, role-model, role-agent, providers, provider")
+        print("Actions: wizard, show, role-model, role-agent, providers, provider, memory")
         sys.exit(1)

{agent_notes-2.22.0 → agent_notes-2.24.0}/agent_notes/commands/doctor.py

@@ -61,16 +61,26 @@ def _check_session_hook(scope: str, issues: list) -> None:
             "SessionStart hook not found — run: agent-notes install to re-add the hook",
         ))
 
+    from ..constants import Hooks
+    from ..services.state_store import load_state
+    state = load_state()
+    if state and state.memory.backend in ("obsidian", "wiki"):
+        if not has_hook(settings_path, "SessionStart", Hooks.MEMORY_BRIDGE):
+            issues.append(Issue(
+                "missing_hook",
+                str(settings_path),
+                "memory-bridge SessionStart hook not found — run: agent-notes install to re-add",
+            ))
+
 
 def check_version_drift(scope: str, issues: list, fix_actions: list) -> None:
     """Check if the installed package version matches the current running version."""
-    from .. import install_state
+    from ..services.state_store import load_current_state, get_scope
     from ..config import get_version
     from ..domain.diagnostics import Issue, FixAction
-    from ..services.state_store import get_scope
     from pathlib import Path
 
-    state = install_state.load_current_state()
+    state = load_current_state()
     if state is None:
         return
 
@@ -96,8 +106,6 @@ def check_version_drift(scope: str, issues: list, fix_actions: list) -> None:
 
 def diagnose(scope: str, fix: bool = False) -> bool:
     """Run all diagnostic checks and optionally apply fixes."""
-    from .. import install_state
-
     print_summary(scope)
 
     issues = []
@@ -120,7 +128,8 @@ def diagnose(scope: str, fix: bool = False) -> bool:
     _check_session_hook(scope, issues)
 
     # Print role→model assignments
-    state = install_state.load_current_state()
+    from ..services.state_store import load_current_state
+    state = load_current_state()
     if state is not None:
         _check_role_models(state)
     

agent_notes-2.24.0/agent_notes/commands/hook.py

@@ -0,0 +1,42 @@
+"""Hook command - Claude Code hook integrations."""
+
+from pathlib import Path
+
+
+def hook(subaction: str) -> None:
+    """Handle hook subactions."""
+    if subaction == "memory-bridge":
+        _memory_bridge()
+
+
+def _memory_bridge() -> None:
+    """SessionStart hook that prints the agent-notes memory index.
+
+    Unconditionally loads and prints the memory index so it is visible in
+    context at the start of every Claude Code session.
+    """
+    try:
+        from .memory._common import _load_memory_config
+        from ..constants import Obsidian, Wiki
+
+        backend, path = _load_memory_config()
+
+        if backend == "none" or backend is None:
+            return
+
+        if backend == "obsidian":
+            index_file = Path(path) / Obsidian.INDEX
+        elif backend == "wiki":
+            index_file = Path(path) / Wiki.DIR / Wiki.INDEX
+        else:
+            # local and any unknown backends: use Index.md at root
+            index_file = Path(path) / "Index.md"
+
+        if not index_file.exists():
+            return
+
+        content = index_file.read_text(encoding="utf-8")
+        print("<!-- agent-notes memory index (auto-loaded) -->")
+        print(content)
+    except Exception:
+        return

{agent_notes-2.22.0 → agent_notes-2.24.0}/agent_notes/commands/info.py

@@ -2,7 +2,7 @@
 
 from pathlib import Path
 
-from .. import install_state
+from ..services.state_store import load_current_state as _load_current_state
 from ..config import get_version, CLAUDE_HOME, Color
 from ._install_helpers import count_skills, count_agents, count_global
 
@@ -49,7 +49,7 @@ def show_info() -> None:
         print(f"  Local:   {Color.CYAN}not detected{Color.NC}")
     
     # State info
-    st = install_state.load_current_state()
+    st = _load_current_state()
     if st is not None:
         print("")
         print("Last install:")

{agent_notes-2.22.0 → agent_notes-2.24.0}/agent_notes/commands/install.py

@@ -3,19 +3,20 @@
 from pathlib import Path
 
 from ..config import Color, PKG_DIR
-from .. import install_state
+from ..services.install_state_builder import build_install_state
+from ..services.state_store import load_current_state, record_install_state, remove_install_state
 from ._install_helpers import _verify_install
 
 
 def install(local: bool = False, copy: bool = False, reconfigure: bool = False) -> None:
     """Build from source and install to targets."""
-    from ..state import get_scope, state_file
+    from ..services.state_store import get_scope, state_file
     from pathlib import Path
-    
+
     scope = "local" if local else "global"
     project_path = Path.cwd().resolve() if local else None
 
-    state = install_state.load_current_state()
+    state = load_current_state()
     existing = get_scope(state, scope, project_path) if state else None
 
     if existing and not reconfigure:
@@ -55,7 +56,7 @@ def install(local: bool = False, copy: bool = False, reconfigure: bool = False)
 
     if existing and reconfigure:
         print(f"Clearing existing {scope} state (--reconfigure) ...")
-        install_state.remove_install_state(scope, project_path)
+        remove_install_state(scope, project_path)
         # Fall through to normal install flow
     
     # Validate args
@@ -88,13 +89,13 @@ def install(local: bool = False, copy: bool = False, reconfigure: bool = False)
     # Record state
     try:
         project_path = Path.cwd() if local else None
-        st = install_state.build_install_state(
+        st = build_install_state(
             mode="copy" if copy else "symlink",
             scope="local" if local else "global",
             repo_root=PKG_DIR.parent,  # repo root (parent of agent_notes pkg)
             project_path=project_path,
         )
-        install_state.record_install_state(st)
+        record_install_state(st)
     except Exception as e:
         print(f"{Color.YELLOW}Warning: failed to write state.json: {e}{Color.NC}")
 
@@ -117,7 +118,7 @@ def uninstall(local: bool = False, global_: bool = False) -> None:
 
         # Remove state entry for this scope
         try:
-            install_state.remove_install_state(scope, project_path)
+            remove_install_state(scope, project_path)
         except Exception as e:
             print(f"{Color.YELLOW}Warning: failed to clear state.json: {e}{Color.NC}")
 

agent_notes-2.24.0/agent_notes/commands/memory/__init__.py

@@ -0,0 +1,104 @@
+"""Manage agent memory stored in ~/.claude/agent-memory/."""
+
+from typing import Optional
+
+from . import _common
+from ._common import _load_memory_config, get_directory_size, format_size, _WIKI_TYPE_MAP
+from .vault import do_vault, do_init, do_index
+from .notes import do_add, do_list, do_show, do_size
+from .transfer import do_export, do_import
+from .wiki import do_ingest, do_query, do_lint, do_scan_raw
+from .reset import do_reset
+
+
+def show_help() -> None:
+    """Show memory command help."""
+    help_text = """Usage: agent-notes memory [command] [args]
+
+Manage agent memory.
+
+Commands:
+  init             Create folder structure and Index.md
+  list             List all agent memories with sizes (default)
+  vault            Show current backend and memory path
+  index            Regenerate Index.md for the current backend
+  add <title> <body>  Add a note (obsidian and wiki backends)
+  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)
+  reset <name>     Clear one agent's memory
+  export           Back up memories to agent-notes/memory-backup/
+  import           Restore from agent-notes/memory-backup/
+  ingest <title> <body>  Ingest source material and fan-out to concepts/entities (wiki backend)
+  query <keyword>  Search wiki pages by keyword (wiki backend)
+  lint             Check wiki health: orphans, broken links, stale index (wiki backend)
+
+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"""
+
+    print(help_text)
+
+
+def memory(action: str = "list", name: Optional[str] = None, extra: Optional[list] = None, description: str = "") -> None:
+    """Manage agent memory."""
+    if action == "list":
+        do_list()
+    elif action == "init":
+        do_init()
+    elif action == "vault":
+        do_vault()
+    elif action == "index":
+        do_index()
+    elif action == "add":
+        # name is title, extra[0] is body
+        if not name:
+            print("Error: add requires a title.")
+            exit(1)
+        body = extra[0] if extra else ""
+        note_type = extra[1] if extra and len(extra) > 1 else "context"
+        agent = extra[2] if extra and len(extra) > 2 else ""
+        project = extra[3] if extra and len(extra) > 3 else ""
+        do_add(name, body, note_type=note_type, agent=agent, project=project, description=description)
+    elif action == "size":
+        do_size()
+    elif action == "show":
+        if not name:
+            print("Error: show requires an agent name.")
+            exit(1)
+        do_show(name)
+    elif action == "reset":
+        do_reset(name)
+    elif action == "export":
+        do_export()
+    elif action == "import":
+        do_import()
+    elif action == "ingest":
+        if not name:
+            do_scan_raw()
+            exit(0)
+        body = extra[0] if extra else ""
+        concepts_csv = extra[1] if extra and len(extra) > 1 else ""
+        entities_csv = extra[2] if extra and len(extra) > 2 else ""
+        tags_csv = extra[3] if extra and len(extra) > 3 else ""
+        concepts = [c.strip() for c in concepts_csv.split(",") if c.strip()] if concepts_csv else None
+        entities = [e.strip() for e in entities_csv.split(",") if e.strip()] if entities_csv else None
+        tags = [t.strip() for t in tags_csv.split(",") if t.strip()] if tags_csv else None
+        do_ingest(name, body, concepts=concepts, entities=entities, tags=tags)
+    elif action == "query":
+        if not name:
+            print("Error: query requires a keyword.")
+            exit(1)
+        do_query(name)
+    elif action == "lint":
+        do_lint()
+    else:
+        print(f"Unknown command: {action}")
+        show_help()
+        exit(1)

agent_notes-2.24.0/agent_notes/commands/memory/_common.py

@@ -0,0 +1,63 @@
+"""Shared helpers for memory subcommands."""
+
+from pathlib import Path
+from typing import Optional
+
+from ...config import MEMORY_DIR
+
+
+_WIKI_TYPE_MAP = {
+    "pattern": "concepts",
+    "decision": "concepts",
+    "mistake": "concepts",
+    "context": "concepts",
+    "concept": "concepts",
+    "concepts": "concepts",
+    "entity": "entities",
+    "entities": "entities",
+    "synthesis": "synthesis",
+    "session": "sessions",
+    "sessions": "sessions",
+    "source": "sources",
+    "sources": "sources",
+}
+
+
+def _load_memory_config():
+    from ...services.state_store import load_state
+    from ...config import memory_dir_for_backend
+    state = load_state()
+    if state is None:
+        return "local", MEMORY_DIR
+    backend = state.memory.backend
+    path = memory_dir_for_backend(backend, state.memory.path)
+    return backend, path
+
+
+def get_directory_size(path: Path) -> int:
+    """Calculate total size of directory in bytes."""
+    total = 0
+    try:
+        for item in path.rglob('*'):
+            if item.is_file():
+                total += item.stat().st_size
+    except (OSError, PermissionError):
+        pass
+    return total
+
+
+def format_size(size_bytes: int) -> str:
+    """Format size in human-readable format."""
+    if size_bytes == 0:
+        return "0B"
+
+    original_size = size_bytes
+    for unit in ['B', 'K', 'M', 'G', 'T']:
+        if original_size < 1024:
+            if unit == 'B':
+                return f"{original_size}B"
+            else:
+                return f"{original_size:.1f}{unit}"
+        original_size /= 1024
+
+    return f"{original_size:.1f}P"