agent-notes 2.0.4__py3-none-any.whl

agent_notes/services/memory_backend.py

@@ -0,0 +1,155 @@
+"""Memory backend implementations for the three storage strategies."""
+
+from __future__ import annotations
+import re
+from datetime import date
+from pathlib import Path
+from typing import Optional
+
+
+OBSIDIAN_CATEGORIES = ["Patterns", "Decisions", "Mistakes", "Context", "Sessions"]
+
+
+def _slug(title: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")[:60]
+
+
+def _today() -> str:
+    return date.today().isoformat()
+
+
+# ── Obsidian backend ───────────────────────────────────────────────────────────
+
+def obsidian_init(vault: Path) -> None:
+    """Create category folders and a stub Index.md if the vault is new."""
+    vault.mkdir(parents=True, exist_ok=True)
+    for cat in OBSIDIAN_CATEGORIES:
+        (vault / cat).mkdir(exist_ok=True)
+    index = vault / "Index.md"
+    if not index.exists():
+        obsidian_regenerate_index(vault)
+
+
+def obsidian_write_note(
+    vault: Path,
+    *,
+    title: str,
+    body: str,
+    note_type: str,  # "pattern"|"decision"|"mistake"|"context"|"session"
+    agent: str = "",
+    project: str = "",
+    tags: list[str] | None = None,
+) -> Path:
+    """Write a structured note to the correct category folder."""
+    category_map = {
+        "pattern": "Patterns",
+        "decision": "Decisions",
+        "mistake": "Mistakes",
+        "context": "Context",
+        "session": "Sessions",
+    }
+    folder = vault / category_map.get(note_type, "Context")
+    folder.mkdir(parents=True, exist_ok=True)
+
+    filename = f"{_today()}-{_slug(title)}.md"
+    path = folder / filename
+
+    frontmatter_lines = [
+        "---",
+        f"date: {_today()}",
+        f"type: {note_type}",
+    ]
+    if agent:
+        frontmatter_lines.append(f"agent: {agent}")
+    if project:
+        frontmatter_lines.append(f"project: {project}")
+    if tags:
+        frontmatter_lines.append(f"tags: [{', '.join(tags)}]")
+    frontmatter_lines.append("---")
+
+    path.write_text("\n".join(frontmatter_lines) + f"\n\n# {title}\n\n{body}\n")
+    obsidian_regenerate_index(vault)
+    return path
+
+
+def obsidian_regenerate_index(vault: Path) -> None:
+    """Regenerate Index.md from all notes in the vault (last 20 per category)."""
+    lines = [f"# Agent Memory Index", f"Last updated: {_today()}", ""]
+    for cat in OBSIDIAN_CATEGORIES:
+        folder = vault / cat
+        if not folder.exists():
+            continue
+        notes = sorted(folder.glob("*.md"), reverse=True)[:20]
+        if not notes:
+            continue
+        lines.append(f"## {cat} ({len(list(folder.glob('*.md')))})")
+        for note in notes:
+            stem = note.stem
+            # Extract title from first H1 if possible
+            try:
+                first_h1 = next(
+                    (l.lstrip("# ").strip() for l in note.read_text().splitlines() if l.startswith("# ")),
+                    stem,
+                )
+            except OSError:
+                first_h1 = stem
+            lines.append(f"- [[{stem}]] — {first_h1}")
+        lines.append("")
+    (vault / "Index.md").write_text("\n".join(lines))
+
+
+def obsidian_list_notes(vault: Path) -> list[dict]:
+    """Return list of note metadata dicts from the vault."""
+    notes = []
+    for cat in OBSIDIAN_CATEGORIES:
+        folder = vault / cat
+        if not folder.exists():
+            continue
+        for f in sorted(folder.glob("*.md")):
+            notes.append({"category": cat, "file": f.name, "path": str(f)})
+    return notes
+
+
+def obsidian_claude_md_section(vault: Path) -> str:
+    return (
+        f"## Agent Memory\n\n"
+        f"Your memory vault is at `{vault}`. Start at `Index.md` to find relevant context.\n"
+        f"Categories: Patterns, Decisions, Mistakes, Context, Sessions.\n"
+        f"Use `agent-notes memory add` to save insights, `agent-notes memory index` to refresh Index.md."
+    )
+
+
+# ── Local backend ──────────────────────────────────────────────────────────────
+
+def local_init(memory_dir: Path) -> None:
+    memory_dir.mkdir(parents=True, exist_ok=True)
+
+
+def local_list_notes(memory_dir: Path) -> list[dict]:
+    if not memory_dir.exists():
+        return []
+    return [
+        {"agent": d.name, "path": str(d), "size": sum(f.stat().st_size for f in d.rglob("*") if f.is_file())}
+        for d in sorted(memory_dir.iterdir()) if d.is_dir()
+    ]
+
+
+def local_regenerate_index(memory_dir: Path) -> None:
+    agents = [d.name for d in sorted(memory_dir.iterdir()) if d.is_dir()] if memory_dir.exists() else []
+    lines = [f"# Agent Memory", f"Last updated: {_today()}", ""]
+    for agent in agents:
+        agent_dir = memory_dir / agent
+        files = list(agent_dir.glob("*.md"))
+        lines.append(f"## {agent} ({len(files)} files)")
+        for f in sorted(files):
+            lines.append(f"- [{f.stem}]({agent}/{f.name})")
+        lines.append("")
+    (memory_dir / "Index.md").write_text("\n".join(lines))
+
+
+def local_claude_md_section(memory_dir: Path) -> str:
+    return (
+        f"## Agent Memory\n\n"
+        f"Your memory is at `{memory_dir}/`. Each agent has its own subdirectory.\n"
+        f"Files are plain markdown — read and write freely."
+    )

agent_notes/services/rendering.py

@@ -0,0 +1,329 @@
+"""Frontmatter and agent file rendering."""
+
+import yaml
+import shutil
+import importlib
+import re
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+
+def expand_includes(text: str, shared_dir: Path) -> str:
+    """Expand include directives in text by substituting shared content.
+    
+    Scans for lines matching `<!-- include: NAME -->` (where NAME is [a-z0-9_-]+)
+    and replaces each entire line with the contents of `shared_dir/NAME.md`.
+    
+    Args:
+        text: Input text that may contain include directives
+        shared_dir: Path to directory containing shared .md files
+    
+    Returns:
+        Text with include directives expanded to their content
+    
+    Raises:
+        ValueError: If an include directive references a file that doesn't exist
+    
+    Notes:
+        - If shared_dir doesn't exist, returns text unchanged (backward compatibility)
+        - Include directives must be on their own line (may have surrounding whitespace)
+        - Included files cannot contain other include directives (non-recursive)
+        - Trailing newlines are stripped from included content to avoid double blanks
+        - Include directives inside code fences are still processed (v1 simplicity)
+    """
+    if not shared_dir.exists():
+        return text
+    
+    # Pattern matches <!-- include: NAME --> on its own line with optional whitespace
+    # NAME must be [a-z0-9_-]+
+    pattern = r'^\s*<!--\s*include:\s*([a-z0-9_-]+)\s*-->\s*$'
+    
+    def replace_include(match):
+        include_name = match.group(1)
+        include_file = shared_dir / f"{include_name}.md"
+        
+        if not include_file.exists():
+            raise ValueError(f"Unknown include: {include_name} (file not found: {include_file})")
+        
+        content = include_file.read_text()
+        # Strip trailing newline to avoid double blanks
+        return content.rstrip('\n')
+    
+    return re.sub(pattern, replace_include, text, flags=re.MULTILINE)
+
+
+def _load_frontmatter_template(template_name):
+    """Load a frontmatter template plugin by name.
+    
+    Args:
+        template_name: Name of the template (e.g., 'claude', 'opencode', None)
+    
+    Returns:
+        The template module, or None if template_name is None
+    
+    Raises:
+        ValueError: if template_name is not a simple identifier (defensive: prevents
+            directory traversal or loading arbitrary modules) or if no such template
+            file exists under agent_notes/data/templates/frontmatter/.
+    """
+    if template_name is None:
+        return None
+    if not isinstance(template_name, str) or not template_name.isidentifier():
+        raise ValueError(
+            f"Invalid frontmatter template name: {template_name!r}. "
+            f"Must be a simple Python identifier (e.g. 'claude', 'opencode')."
+        )
+    try:
+        return importlib.import_module(f"agent_notes.data.templates.frontmatter.{template_name}")
+    except ModuleNotFoundError as e:
+        raise ValueError(
+            f"Frontmatter template '{template_name}' not found. "
+            f"Expected agent_notes/data/templates/frontmatter/{template_name}.py to exist. "
+            f"Original error: {e}"
+        ) from e
+
+
+def generate_agent_files(agents_config: Dict[str, Any], tiers: Dict[str, Any], 
+                         state=None, scope='global', project_path=None) -> list[Path]:
+    """Generate agent files for all CLI backends.
+    
+    Args:
+        agents_config: Dict of agent configurations from agents.yaml
+        tiers: Dict mapping tiers to model names per backend (legacy fallback)
+        state: Optional State object for role-based model resolution
+        scope: 'global' or 'local' (only used if state is provided)
+        project_path: Path for local scope (only used if state is provided and scope='local')
+    
+    If state is None, behaves exactly as before (uses tiers dict).
+    If state is provided, tries state-driven resolution first, falls back to tiers on miss.
+    """
+    from ..registries.cli_registry import load_registry
+    from ..registries.model_registry import load_model_registry
+    from .. import state as state_module
+    from ..config import AGENTS_DIR, DIST_DIR
+    
+    generated_files = []
+
+    from ..services.user_config import load_user_config, resolve_agent_role, resolve_role_model, get_patch, merge_configs
+
+    user_config = load_user_config()
+    # Merge project-level config if provided
+    if project_path is not None:
+        project_config_file = Path(project_path) / ".claude" / "agent-notes.yaml"
+        if project_config_file.exists():
+            from ..services.user_config import load_user_config as _load
+            project_config = _load(project_config_file)
+            user_config = merge_configs(user_config, project_config)
+
+    registry = load_registry()
+    model_registry = None  # Lazy load only if needed
+    scope_state = None
+    
+    # Get scope state if state is provided
+    if state is not None:
+        scope_state = state_module.get_scope(state, scope, project_path)
+    
+    for agent_name, agent_config in agents_config.items():
+        # Read the source prompt
+        prompt_file = AGENTS_DIR / f'{agent_name}.md'
+        if not prompt_file.exists():
+            print(f"Warning: Missing source file {prompt_file}")
+            continue
+        
+        prompt_content = prompt_file.read_text()
+        
+        # Expand shared-content include directives (<!-- include: NAME -->)
+        # No-op if shared/ directory is absent.
+        prompt_content = expand_includes(prompt_content, AGENTS_DIR / "shared")
+        
+        # Generate for each backend that supports agents
+        for backend in registry.all():
+            if not backend.supports("agents"):
+                continue
+                
+            # Skip if agent is excluded for this backend
+            # Check both new backend-specific exclusion and legacy exclude_flag
+            excluded = False
+            
+            # New backend-specific exclusion: check if backend.name key exists and has exclude: true
+            if backend.name in agent_config and isinstance(agent_config[backend.name], dict):
+                backend_cfg = agent_config[backend.name]
+                if backend_cfg.get("exclude"):
+                    excluded = True
+            
+            # Legacy exclusion: check if exclude_flag is set (for backward compat)
+            exclude_flag = backend.exclude_flag
+            if not excluded and exclude_flag and agent_config.get(exclude_flag):
+                excluded = True
+            
+            if excluded:
+                continue
+            
+            # Get frontmatter generator
+            frontmatter_type = backend.features.get("frontmatter")
+            if frontmatter_type is None:
+                continue  # Skip backends without frontmatter (like copilot)
+            
+            # Load template dynamically
+            template = _load_frontmatter_template(frontmatter_type)
+            if template is None:
+                continue
+            
+            # Resolve model. Resolution chain:
+            #   1. State-driven: state.clis[backend].role_models[role] -> model_id
+            #   2. Role-class fallback: role.typical_class matched against
+            #      any model's class, with a compatible provider for this backend
+            #   3. Legacy tier fallback: agent_config['tier'] -> tiers[tier][backend.name]
+            model_str = None
+            agent_role = resolve_agent_role(agent_name, agent_config.get('role'), user_config)
+            
+            if (scope_state is not None and 
+                agent_role is not None and 
+                backend.name in scope_state.clis and
+                agent_role in scope_state.clis[backend.name].role_models):
+                
+                # Step 1: state-driven resolution
+                model_id = scope_state.clis[backend.name].role_models[agent_role]
+                
+                # Lazy load model registry
+                if model_registry is None:
+                    model_registry = load_model_registry()
+                
+                try:
+                    model = model_registry.get(model_id)
+                    resolved = model.resolve_for_providers(list(backend.accepted_providers))
+                    if resolved is not None:
+                        _provider, alias_str = resolved
+                        model_str = alias_str
+                except KeyError:
+                    pass  # fall through to class/tier fallback
+            
+            # User config override: explicit model for this role+backend
+            if model_str is None:
+                user_model = resolve_role_model(agent_role, backend.name, user_config)
+                if user_model:
+                    model_str = user_model
+
+            # Step 2: role.typical_class fallback — the "works from shipped YAMLs
+            # with zero state" path. Loads the role and picks any model whose
+            # class matches role.typical_class and which has an alias for one
+            # of this backend's accepted providers.
+            if model_str is None and agent_role is not None:
+                if model_registry is None:
+                    model_registry = load_model_registry()
+                try:
+                    from ..registries.role_registry import load_role_registry
+                    role_registry = load_role_registry()
+                    role = role_registry.get(agent_role)
+                except (KeyError, FileNotFoundError, ValueError):
+                    role = None
+                
+                if role is not None:
+                    # Prefer newer model IDs when multiple match the class.
+                    # Registries are sorted ascending by id, so iterate reversed
+                    # to pick e.g. claude-opus-4-7 over claude-opus-4-6.
+                    for model in reversed(model_registry.all()):
+                        if model.model_class != role.typical_class:
+                            continue
+                        resolved = model.resolve_for_providers(list(backend.accepted_providers))
+                        if resolved is not None:
+                            _provider, alias_str = resolved
+                            model_str = alias_str
+                            break
+            
+            # Step 3: legacy tier fallback (for pre-v1.1 agents.yaml files that
+            # still declare `tier:` instead of `role:`).
+            if model_str is None:
+                if 'tier' not in agent_config:
+                    raise ValueError(
+                        f"Agent '{agent_name}' has role='{agent_role}' but no model could be "
+                        f"resolved for backend '{backend.name}'. Tried: state.role_models, "
+                        f"role.typical_class->model.class matching, and legacy 'tier' fallback. "
+                        f"Check that data/roles/{agent_role}.yaml exists and that at least one "
+                        f"model in data/models/*.yaml has class={role.typical_class if 'role' in locals() and role else '?'} "
+                        f"with an alias for one of {list(backend.accepted_providers)}."
+                    )
+                tier = agent_config['tier']
+                if backend.name not in tiers[tier]:
+                    raise ValueError(f"tier '{tier}' missing model for CLI '{backend.name}' in agents.yaml")
+                model_str = tiers[tier][backend.name]
+            
+            # Build context for template
+            ctx = {
+                'agent_name': agent_name,
+                'agent_config': agent_config,
+                'model_str': model_str,
+                'backend_name': backend.name,
+                'backend': backend,
+            }
+            
+            # Generate frontmatter using template
+            frontmatter = template.render(ctx)
+            
+            # Apply post-processing transformation (e.g., strip memory section)
+            content = template.post_process(prompt_content, ctx)
+
+            # Apply user patch if present
+            patch = get_patch(agent_name, user_config)
+            if patch:
+                content = content.rstrip() + "\n\n" + patch.strip()
+
+            # Combine and write
+            full_content = f"{frontmatter}\n\n{content}"
+            
+            # Write to backend's agents directory
+            from ..services import installer
+            agents_dir = installer.dist_source_for(backend, "agents")
+            if agents_dir is None:
+                agents_dir = DIST_DIR / backend.name / "agents"
+            
+            agent_file = agents_dir / f'{agent_name}.md'
+            agent_file.parent.mkdir(parents=True, exist_ok=True)
+            agent_file.write_text(full_content)
+            generated_files.append(agent_file)
+    
+    return generated_files
+
+
+def render_globals() -> list[Path]:
+    """Copy global files to destinations."""
+    from ..config import (
+        GLOBAL_CLAUDE_MD, GLOBAL_OPENCODE_MD, GLOBAL_COPILOT_MD,
+        DIST_CLAUDE_DIR, DIST_OPENCODE_DIR, DIST_GITHUB_DIR
+    )
+    
+    copied_files = []
+    
+    # Copy global-claude.md to CLAUDE.md
+    claude_global_content = GLOBAL_CLAUDE_MD.read_text()
+    claude_global = DIST_CLAUDE_DIR / 'CLAUDE.md'
+    claude_global.parent.mkdir(parents=True, exist_ok=True)
+    claude_global.write_text(claude_global_content)
+    copied_files.append(claude_global)
+    
+    # Copy global-opencode.md to AGENTS.md
+    opencode_global_content = GLOBAL_OPENCODE_MD.read_text()
+    agents_global = DIST_OPENCODE_DIR / 'AGENTS.md'
+    agents_global.parent.mkdir(parents=True, exist_ok=True)
+    agents_global.write_text(opencode_global_content)
+    copied_files.append(agents_global)
+    
+    # Copy global-copilot.md to copilot-instructions.md
+    copilot_content = GLOBAL_COPILOT_MD.read_text()
+    copilot_global = DIST_GITHUB_DIR / 'copilot-instructions.md'
+    copilot_global.parent.mkdir(parents=True, exist_ok=True)
+    copilot_global.write_text(copilot_content)
+    copied_files.append(copilot_global)
+    
+    return copied_files
+
+
+def load_agents_config() -> tuple[Dict[str, Any], Dict[str, Any]]:
+    """Load agents configuration from agents.yaml."""
+    from ..config import AGENTS_YAML
+    
+    if not AGENTS_YAML.exists():
+        raise FileNotFoundError(f"Configuration file not found: {AGENTS_YAML}")
+    
+    config = yaml.safe_load(AGENTS_YAML.read_text())
+    return config.get('agents', {}), config.get('tiers', {})

agent_notes/services/session_context.py

@@ -0,0 +1,23 @@
+"""Generate the session context file injected by the SessionStart hook."""
+from __future__ import annotations
+from pathlib import Path
+
+
+def _template_path() -> Path:
+    return Path(__file__).parent.parent / "data" / "hooks" / "session-context.md.tpl"
+
+
+def render_context(agents: list[str], version: str) -> str:
+    tpl = _template_path().read_text()
+    if agents:
+        agents_list = "\n".join(f"- {name}" for name in sorted(agents))
+    else:
+        agents_list = "- (see ~/.claude/agents/ for installed agents)"
+    return (tpl
+            .replace("{{version}}", version)
+            .replace("{{agents_list}}", agents_list))
+
+
+def write_context(dest: Path, agents: list[str], version: str) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(render_context(agents, version))

agent_notes/services/settings_writer.py

@@ -0,0 +1,79 @@
+"""Read, merge, and write Claude Code settings.json without clobbering user config."""
+import json
+from pathlib import Path
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    result = dict(base)
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def install_hook(settings_path: Path, hook_event: str, command: str) -> None:
+    """Add a hook entry to settings.json. Idempotent — does not duplicate."""
+    data = {}
+    if settings_path.exists():
+        try:
+            data = json.loads(settings_path.read_text())
+        except json.JSONDecodeError:
+            pass
+
+    # Check if already present
+    existing = data.get("hooks", {}).get(hook_event, [])
+    for entry in existing:
+        for h in entry.get("hooks", []):
+            if h.get("command") == command:
+                return  # already installed
+
+    hook_entry = {
+        "hooks": {
+            hook_event: [
+                {"matcher": "", "hooks": [{"type": "command", "command": command}]}
+            ]
+        }
+    }
+    merged = _deep_merge(data, hook_entry)
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    settings_path.write_text(json.dumps(merged, indent=2) + "\n")
+
+
+def remove_hook(settings_path: Path, hook_event: str, command: str) -> None:
+    """Remove a specific hook entry from settings.json."""
+    if not settings_path.exists():
+        return
+    try:
+        data = json.loads(settings_path.read_text())
+    except json.JSONDecodeError:
+        return
+
+    hooks = data.get("hooks", {}).get(hook_event, [])
+    cleaned = [
+        entry for entry in hooks
+        if not any(h.get("command") == command for h in entry.get("hooks", []))
+    ]
+    if cleaned:
+        data["hooks"][hook_event] = cleaned
+    else:
+        data.get("hooks", {}).pop(hook_event, None)
+        if not data.get("hooks"):
+            data.pop("hooks", None)
+    settings_path.write_text(json.dumps(data, indent=2) + "\n")
+
+
+def has_hook(settings_path: Path, hook_event: str, command: str) -> bool:
+    """Return True if the hook is present in settings.json."""
+    if not settings_path.exists():
+        return False
+    try:
+        data = json.loads(settings_path.read_text())
+    except json.JSONDecodeError:
+        return False
+    for entry in data.get("hooks", {}).get(hook_event, []):
+        for h in entry.get("hooks", []):
+            if h.get("command") == command:
+                return True
+    return False