@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/bin/hindsight-project-index

@@ -0,0 +1,530 @@
+#!/usr/bin/env python3
+"""Index tracked project docs, tree-sitter code outlines and Obsidian vaults into a memory provider (Hindsight by default)."""
+
+import argparse
+import fcntl
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import code_outline
+import index_config
+import sinks
+from sinks.hindsight import DEFAULT_URL, HttpError  # noqa: F401  (HttpError stays importable from here)
+
+
+SKIP_NAMES = {"auth.json", "credentials.json", "id_rsa", "id_ed25519"}
+VAULT_SKIP_DIRS = {".obsidian", ".trash"}
+DOC_SUFFIXES = {".md", ".mdx"}
+HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*$")
+WIKILINK = re.compile(r"!?\[\[([^\]|#\n]+)[^\]\n]*\]\]")
+INLINE_TAG = re.compile(r"(?<![\w/#&])#([A-Za-z][\w/-]*)")
+DEFAULT_STATE = Path.home() / ".cache/hindsight-project-index/state.json"
+AGENT_CONFIG = Path.home() / ".hindsight/coding-agent.json"
+PERSONAL_MEMORY_AGENT_CONFIG = Path.home() / ".config/personal-memory/coding-agent.json"
+
+
+def scan_root(root: Path, depth: int, skip_dirs: frozenset[str], want_vaults: bool) -> tuple[list[Path], list[Path]]:
+    """Return the outermost git repositories and, when want_vaults, the .obsidian folders within depth levels of root."""
+    repos: list[Path] = []
+    vaults: list[Path] = []
+    if not root.is_dir():
+        print(f"{root}: root not found, skipped", file=sys.stderr)
+        return repos, vaults
+    for child in root.iterdir():
+        if not child.is_dir() or child.name.startswith("."):
+            continue
+        for current, dirs, _files in os.walk(child):
+            here = Path(current)
+            if len(here.relative_to(root).parts) > depth:
+                dirs[:] = []
+                continue
+            is_repo = (here / ".git").exists()
+            is_vault = want_vaults and (here / ".obsidian").is_dir()
+            if is_repo:
+                repos.append(here)
+            if is_vault:
+                vaults.append(here)
+            if is_repo or is_vault:
+                dirs[:] = []
+                continue
+            dirs[:] = [name for name in dirs if name not in skip_dirs and not name.startswith(".")]
+    return repos, vaults
+
+
+def is_git_repo(path: Path) -> bool:
+    return subprocess.run(["git", "rev-parse", "--show-toplevel"], cwd=path, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL).returncode == 0
+
+
+def discover(config: index_config.Config) -> tuple[list[Path], list[Path], list[tuple[str, Path]]]:
+    """Return repositories, Obsidian vaults, and markdown directory sources (kind, path)."""
+    repos: set[Path] = set(config.repos)
+    vaults: set[Path] = set(config.vault_paths)
+    markdown: list[tuple[str, Path]] = list(config.markdown_sources())
+    for root in config.roots:
+        found_repos, found_vaults = scan_root(root.path, root.depth, config.skip_dirs, config.vault_auto)
+        repos.update(found_repos)
+        vaults.update(found_vaults)
+    selected_repos = []
+    for repo in sorted(repos):
+        if is_git_repo(repo):
+            selected_repos.append(repo)
+        else:
+            print(f"{repo}: not a git repository, skipped", file=sys.stderr)
+    selected_vaults = []
+    for vault in sorted(vaults):
+        if vault.is_dir():
+            selected_vaults.append(vault)
+        else:
+            print(f"{vault}: vault not found, skipped", file=sys.stderr)
+    selected_markdown: list[tuple[str, Path]] = []
+    for kind, path in markdown:
+        if path.is_dir():
+            selected_markdown.append((kind, path))
+        else:
+            print(f"{path}: {kind} path not found, skipped", file=sys.stderr)
+    selected_markdown.sort(key=lambda item: (item[0], item[1]))
+    return selected_repos, selected_vaults, selected_markdown
+
+
+def _config(config: index_config.Config | None) -> index_config.Config:
+    return config if config is not None else index_config.parse(None)
+
+
+def tracked_files(repo: Path, config: index_config.Config | None = None) -> list[Path]:
+    config = _config(config)
+    raw = subprocess.run(["git", "ls-files", "-z"], cwd=repo, capture_output=True, check=True).stdout
+    paths = []
+    for item in raw.split(b"\0"):
+        if not item:
+            continue
+        rel = Path(os.fsdecode(item))
+        if any(part in config.skip_dirs for part in rel.parts) or rel.name in SKIP_NAMES:
+            continue
+        if rel.name.startswith(".env") or any(word in rel.name.lower() for word in ("secret", "credential", "private_key")):
+            continue
+        path = repo / rel
+        if path.is_file() and not path.is_symlink() and path.stat().st_size <= config.max_file_bytes:
+            paths.append(rel)
+    return paths
+
+
+def doc_chunks(text: str, limit: int = 2400) -> list[tuple[str, str]]:
+    sections = []
+    stack: list[str] = []
+    body: list[str] = []
+
+    def flush() -> None:
+        content = "\n".join(body).strip()
+        if content:
+            sections.append((" / ".join(stack) or "Introduction", content))
+
+    for line in text.splitlines():
+        match = HEADING.match(line)
+        if match:
+            flush()
+            body = []
+            depth = len(match.group(1))
+            stack = stack[: depth - 1] + [match.group(2)]
+        else:
+            body.append(line)
+    flush()
+    chunks = []
+    for heading, content in sections:
+        paragraphs = re.split(r"\n\s*\n", content)
+        part = ""
+        for paragraph in paragraphs:
+            for segment in (paragraph[i : i + limit] for i in range(0, len(paragraph), limit)):
+                if part and len(part) + len(segment) + 2 > limit:
+                    chunks.append((heading, part))
+                    part = ""
+                part = f"{part}\n\n{segment}".strip()
+        if part:
+            chunks.append((heading, part))
+    return chunks
+
+
+def source_documents(repo: Path, config: index_config.Config | None = None) -> dict[str, dict]:
+    """Return the repository's prose chunks and tree-sitter code outlines, keyed by stable document ID."""
+    documents = {}
+    for rel in tracked_files(repo, config):
+        kind = "doc" if rel.suffix.lower() in DOC_SUFFIXES else "code" if code_outline.language_for(rel.as_posix()) else None
+        if kind is None:
+            continue
+        if kind == "code":
+            outline = code_outline.outline(rel.as_posix(), (repo / rel).read_bytes())
+            if not outline:
+                continue
+            parts = [("outline", outline)]
+        else:
+            try:
+                parts = doc_chunks((repo / rel).read_text(encoding="utf-8"))
+            except UnicodeError:
+                continue
+        for index, (heading, content) in enumerate(parts):
+            label = f"{kind}:{repo.as_posix()}:{rel.as_posix()}:{heading}:{index}"
+            doc_id = "project-index:v1:" + hashlib.sha256(label.encode()).hexdigest()[:32]
+            payload = f"Project: {repo.name}\nSource: {rel.as_posix()}\nSection: {heading}\n\n{content}"
+            documents[doc_id] = {
+                "content": payload,
+                "path": rel.as_posix(),
+                "kind": kind,
+                "digest": hashlib.sha256(payload.encode()).hexdigest(),
+                "context": f"Project {repo.name} {kind} source",
+                "metadata": {"path": rel.as_posix(), "kind": kind},
+            }
+    return documents
+
+
+def slugify(name: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+
+def vault_bank(vault: Path, config: index_config.Config | None = None) -> str:
+    return _config(config).bank_for(vault) or "obsidian::" + slugify(vault.name)
+
+
+def markdown_bank(kind: str, root: Path, config: index_config.Config | None = None) -> str:
+    cfg = _config(config)
+    mapped = cfg.bank_for(root)
+    if mapped:
+        return mapped
+    prefix = {"notes": "notes", "papers": "papers", "bookmarks": "bookmarks", "feed": "feed"}.get(kind, "notes")
+    return f"{prefix}::{slugify(root.name)}"
+
+
+def split_frontmatter(text: str) -> tuple[list[str], str]:
+    if not text.startswith("---\n"):
+        return [], text
+    end = text.find("\n---", 3)
+    if end == -1:
+        return [], text
+    block = text[4:end].splitlines()
+    body = text[end + 4 :].lstrip("\n")
+    tags: list[str] = []
+    for index, line in enumerate(block):
+        if not line.startswith("tags:"):
+            continue
+        value = line[len("tags:") :].strip()
+        if value:
+            tags = re.split(r"[\[\],]", value)
+        else:
+            for following in block[index + 1 :]:
+                match = re.match(r"^\s*-\s+(.+)$", following)
+                if not match:
+                    break
+                tags.append(match.group(1))
+        break
+    cleaned = [tag.strip().strip("\"'").lstrip("#").strip() for tag in tags]
+    return [tag for tag in cleaned if tag], body
+
+
+MARKDOWN_SUFFIXES = {
+    "notes": (".md",),
+    "papers": (".md", ".txt"),
+    "bookmarks": (".md", ".html", ".htm", ".txt"),
+    "feed": (".md",),
+}
+
+
+def vault_documents(vault: Path, config: index_config.Config | None = None, *, kind: str = "notes") -> dict[str, dict]:
+    config = _config(config)
+    suffixes = MARKDOWN_SUFFIXES.get(kind, (".md",))
+    documents = {}
+    for current, dirs, files in os.walk(vault):
+        dirs[:] = [name for name in dirs if name not in VAULT_SKIP_DIRS]
+        for name in files:
+            path = Path(current) / name
+            if path.suffix.lower() not in suffixes or path.is_symlink():
+                continue
+            if name.startswith(".env") or any(word in name.lower() for word in ("secret", "credential", "private_key")):
+                continue
+            if path.stat().st_size > config.max_file_bytes:
+                continue
+            try:
+                text = path.read_text(encoding="utf-8")
+            except UnicodeError:
+                continue
+            if path.suffix.lower() in (".html", ".htm"):
+                text = re.sub(r"(?is)<(script|style).*?>.*?</\1>", " ", text)
+                text = re.sub(r"<[^>]+>", " ", text)
+                text = re.sub(r"\s+", " ", text).strip()
+            rel = path.relative_to(vault).as_posix()
+            frontmatter_tags, body = split_frontmatter(text)
+            tags = list(dict.fromkeys(frontmatter_tags + INLINE_TAG.findall(body)))
+            links = sorted({target.strip() for target in WIKILINK.findall(body) if target.strip()})
+            for index, (heading, content) in enumerate(doc_chunks(body)):
+                label = f"note:{vault.as_posix()}:{rel}:{heading}:{index}"
+                doc_id = "obsidian-index:v1:" + hashlib.sha256(label.encode()).hexdigest()[:32]
+                payload = f"Vault: {vault.name}\nSource: {rel}\nSection: {heading}\n\n{content}"
+                metadata = {"path": rel, "kind": "note"}
+                if links:
+                    metadata["links"] = ", ".join(links)
+                documents[doc_id] = {
+                    "content": payload,
+                    "path": rel,
+                    "kind": "note",
+                    "digest": hashlib.sha256(payload.encode()).hexdigest(),
+                    "context": f"Obsidian vault {vault.name} note",
+                    "metadata": metadata,
+                    "tags": tags,
+                }
+    return documents
+
+
+def acquire_state_lock(state_path: Path):
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = state_path.with_name(state_path.name + ".lock").open("w")
+    fcntl.flock(handle, fcntl.LOCK_EX)
+    return handle
+
+
+def save_state(path: Path, state: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp = path.with_suffix(".tmp")
+    temp.write_text(json.dumps(state, indent=2, sort_keys=True))
+    temp.replace(path)
+
+
+def bank_id(repo: Path, config: index_config.Config | None = None) -> str:
+    # Order: index.yml banks, openmem mapping, legacy Hindsight mapping, repository name.
+    configured = _config(config).bank_for(repo)
+    if configured:
+        return configured
+    for config_path in (PERSONAL_MEMORY_AGENT_CONFIG, AGENT_CONFIG):
+        agent = json.loads(config_path.read_text()) if config_path.exists() else {}
+        mappings = agent.get("mapPathToBank", {})
+        resolved = sorted(
+            ((Path(prefix).expanduser().resolve(), bank) for prefix, bank in mappings.items()),
+            key=lambda item: len(str(item[0])),
+            reverse=True,
+        )
+        for path, bank in resolved:
+            if repo == path or path in repo.parents:
+                return bank
+    return "coding-agent::" + project_name(repo)
+
+
+def project_name(repo: Path) -> str:
+    """Return the shared project name for linked worktrees, otherwise the repo directory name."""
+    root = repo.resolve()
+    git_entry = root / ".git"
+    try:
+        if git_entry.is_dir():
+            git_dir = git_entry
+        elif git_entry.is_file():
+            match = re.match(r"^gitdir:\s*(.+?)\s*$", git_entry.read_text())
+            if not match:
+                return root.name
+            git_dir = Path(match.group(1))
+            if not git_dir.is_absolute():
+                git_dir = (root / git_dir).resolve()
+        else:
+            return root.name
+
+        common_file = git_dir / "commondir"
+        common_dir = (git_dir / common_file.read_text().strip()).resolve() if common_file.exists() else git_dir
+        if git_dir.parent.name == "worktrees" and common_dir.name == ".git":
+            return common_dir.parent.name
+    except OSError:
+        pass
+    return root.name
+
+
+def kinds_key(source: Path) -> str:
+    return f"{source}::kinds"
+
+
+# Banks whose sink flush() has not completed. A distinct top-level key (source keys are absolute paths, so it
+# cannot collide). It exists only while a flush is pending and only for sinks that define flush(), so a state
+# file written for a sink without flush() (Hindsight) never contains it.
+PENDING_FLUSH_KEY = "::flush-pending"
+
+
+def pending_flush_banks(state: dict) -> set[str]:
+    return set(state.get(PENDING_FLUSH_KEY, []))
+
+
+def set_pending_flush(state: dict, state_path: Path, banks: set[str]) -> None:
+    if banks:
+        state[PENDING_FLUSH_KEY] = sorted(banks)
+    else:
+        state.pop(PENDING_FLUSH_KEY, None)
+    save_state(state_path, state)
+
+
+def sync(source: Path, bank: str, documents: dict[str, dict], sink: sinks.Sink, state: dict, state_path: Path, apply: bool, limit: int | None, kind: str | None) -> tuple[int, int]:
+    if kind:
+        documents = {key: value for key, value in documents.items() if value["kind"] == kind}
+    old = state.get(str(source), {})
+    kinds = state.get(kinds_key(source), {})
+    changed = {key: value for key, value in documents.items() if old.get(key) != value["digest"]}
+    if limit is not None:
+        changed = dict(list(changed.items())[:limit])
+    stale = set(old) - set(documents) if limit is None and kind is None else set()
+    if apply:
+        # Optional flush hook (async-ingest sinks). A flush still pending from an earlier run is retried here.
+        flushable = callable(getattr(sink, "flush", None))
+        flush_due = flushable and bank in pending_flush_banks(state)
+        if changed:
+            sink.prepare(bank)
+        if flushable and (changed or stale) and not flush_due:
+            # Recorded before the first write: the per-document saves below persist digests, so without the
+            # marker a failed flush would never be retried.
+            set_pending_flush(state, state_path, pending_flush_banks(state) | {bank})
+            flush_due = True
+        for doc_id, value in changed.items():
+            sink.retain(bank, doc_id, value["content"], tags=value.get("tags"), metadata=value["metadata"], context=value["context"])
+            old[doc_id] = value["digest"]
+            kinds[doc_id] = value["kind"]
+            state[str(source)] = old
+            state[kinds_key(source)] = kinds
+            save_state(state_path, state)
+        for doc_id in sorted(stale):
+            # A document already gone (never retained, or deleted server-side) is not an error; drop it from the manifest.
+            sink.delete(bank, doc_id)
+            old.pop(doc_id)
+            kinds.pop(doc_id, None)
+            save_state(state_path, state)
+        if flush_due:
+            # Once per bank batch, not per document. The marker is cleared only after a successful flush.
+            sinks.flush_sink(sink, bank)
+            set_pending_flush(state, state_path, pending_flush_banks(state) - {bank})
+        state[str(source)] = old
+        state[kinds_key(source)] = kinds
+    return len(changed), len(stale)
+
+
+def sync_repo(repo: Path, sink: sinks.Sink, state: dict, state_path: Path, apply: bool, limit: int | None, kind: str | None, config: index_config.Config | None = None) -> tuple[int, int]:
+    return sync(repo, bank_id(repo, config), source_documents(repo, config), sink, state, state_path, apply, limit, kind)
+
+
+def sync_vault(vault: Path, sink: sinks.Sink, state: dict, state_path: Path, apply: bool, limit: int | None, config: index_config.Config | None = None) -> tuple[int, int]:
+    return sync(vault, vault_bank(vault, config), vault_documents(vault, config), sink, state, state_path, apply, limit, None)
+
+
+def sync_markdown(kind: str, root: Path, sink: sinks.Sink, state: dict, state_path: Path, apply: bool, limit: int | None, config: index_config.Config | None = None) -> tuple[int, int]:
+    return sync(root, markdown_bank(kind, root, config), vault_documents(root, config, kind=kind), sink, state, state_path, apply, limit, None)
+
+
+def load_opt_in_paths(config: Path) -> list[Path] | None:
+    if not config.exists():
+        print(f"warning: {config} not found; indexing every source under --home", file=sys.stderr)
+        return None
+    paths = json.loads(config.read_text()).get("optInPaths")
+    if paths is None:
+        return None
+    return [Path(item).expanduser().resolve() for item in paths]
+
+
+def opted_in(path: Path, allowed: list[Path] | None) -> bool:
+    return allowed is None or any(path == root or root in path.parents for root in allowed)
+
+
+def selected_sources(args: argparse.Namespace, config: index_config.Config) -> list[tuple[str, Path]]:
+    # Explicit --repo or --vault narrows the run to exactly those sources.
+    if args.repo or args.vault or args.notes or args.papers or args.bookmarks or args.feed:
+        return (
+            [("repo", path) for path in args.repo or []]
+            + [("vault", path) for path in args.vault or []]
+            + [("notes", path) for path in args.notes or []]
+            + [("papers", path) for path in args.papers or []]
+            + [("bookmarks", path) for path in args.bookmarks or []]
+            + [("feed", path) for path in args.feed or []]
+        )
+    repos, vaults, markdown = discover(config)
+    return (
+        [("repo", repo) for repo in repos]
+        + [("vault", vault) for vault in vaults]
+        + [(kind, path) for kind, path in markdown]
+    )
+
+
+def resolve_url(sink_name: str, explicit: str | None) -> str | None:
+    """--url wins. Otherwise $HINDSIGHT_URL for the hindsight sink (then its default), $MEMORY_API_URL for any other."""
+    if explicit:
+        return explicit
+    if sink_name == "hindsight":
+        return os.environ.get("HINDSIGHT_URL") or DEFAULT_URL
+    return os.environ.get("MEMORY_API_URL") or None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--config", type=Path, help="index.yml to use (default: $HINDSIGHT_INDEX_CONFIG, ~/.config/hindsight/index.yml, then config/index.yml)")
+    parser.add_argument("--repo", type=Path, action="append", help="index only these repositories (repeatable)")
+    parser.add_argument("--vault", type=Path, action="append", help="index an Obsidian vault (repeatable)")
+    parser.add_argument("--notes", type=Path, action="append", help="index a markdown notes folder (repeatable)")
+    parser.add_argument("--papers", type=Path, action="append", help="index a papers library folder (markdown exports; repeatable)")
+    parser.add_argument("--bookmarks", type=Path, action="append", help="index a bookmarks export folder (repeatable)")
+    parser.add_argument("--feed", type=Path, action="append", help="index feed-sync markdown cache (repeatable)")
+    parser.add_argument("--sink", default=os.environ.get("MEMORY_SINK") or sinks.DEFAULT_SINK, help="memory provider to write to (default: $MEMORY_SINK, then %(default)s); registered: " + ", ".join(sinks.registered_sinks()))
+    parser.add_argument("--url", help="provider API base URL (default: $HINDSIGHT_URL for the hindsight sink, $MEMORY_API_URL for other sinks, then the sink's own default)")
+    parser.add_argument("--state", type=Path, default=DEFAULT_STATE)
+    parser.add_argument("--limit", type=int, help="at most N changed documents per source; disables deletion")
+    parser.add_argument("--kind", choices=("doc", "code"), help="index only documentation or code in repositories; disables deletion")
+    parser.add_argument("--apply", action="store_true", help="write to the memory provider")
+    parser.add_argument("--list", action="store_true", help="print the selected sources as 'kind<TAB>path' and exit")
+    args = parser.parse_args()
+
+    if args.sink not in sinks.registered_sinks():
+        print(f"unknown sink {args.sink!r}; registered sinks: {', '.join(sinks.registered_sinks())}", file=sys.stderr)
+        return 2
+    try:
+        config = index_config.load(args.config)
+    except index_config.ConfigError as error:
+        print(f"config error: {error}", file=sys.stderr)
+        return 2
+    allowed = load_opt_in_paths(AGENT_CONFIG)
+    sources = []
+    for kind, path in selected_sources(args, config):
+        path = path.expanduser().resolve()
+        if not opted_in(path, allowed):
+            print(f"{path}: skipped (outside optInPaths in {AGENT_CONFIG})")
+        elif config.is_excluded(path):
+            print(f"{path}: skipped (matches exclude in {config.source})", file=sys.stderr)
+        else:
+            sources.append((kind, path))
+    if args.list:
+        for kind, path in sources:
+            print(f"{kind}\t{path}")
+        return 0
+
+    sink = None
+    if args.apply:
+        try:
+            sink = sinks.get_sink(args.sink, url=resolve_url(args.sink, args.url))
+        except ValueError as error:  # includes sinks.UnknownSinkError
+            print(f"sink error: {error}", file=sys.stderr)
+            return 2
+    # Held until exit: the watcher and manual runs must not overwrite each other's state file.
+    _state_lock = acquire_state_lock(args.state) if args.apply else None  # held until exit
+    state = json.loads(args.state.read_text()) if args.state.exists() else {}
+    failed = 0
+    for kind, path in sources:
+        if kind in ("vault", "notes", "papers", "bookmarks", "feed") and args.kind:
+            continue
+        try:
+            if kind == "repo":
+                changed, stale = sync_repo(path, sink, state, args.state, args.apply, args.limit, args.kind, config)
+            elif kind in ("notes", "papers", "bookmarks", "feed"):
+                changed, stale = sync_markdown(kind, path, sink, state, args.state, args.apply, args.limit, config)
+            else:
+                changed, stale = sync_vault(path, sink, state, args.state, args.apply, args.limit, config)
+            print(f"{path}: {changed} to retain, {stale} stale" + (" (applied)" if args.apply else " (dry run)"))
+            if args.apply:
+                save_state(args.state, state)
+        except Exception as error:  # one failing source must not abort the others
+            failed += 1
+            print(f"{path}: {type(error).__name__}: {error}", file=sys.stderr)
+    if failed:
+        print(f"{failed} source(s) failed", file=sys.stderr)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/cli/coding-agent/access-policy.mjs

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const accessConfigPath = (home) => path.join(home, ".config", "personal-memory", "coding-agent.json");
+
+/** Read policy config. A missing file keeps the historical device-wide default; all other read/parse errors deny. */
+export function readAccessConfig(home) {
+  try {
+    const config = JSON.parse(fs.readFileSync(accessConfigPath(home), "utf8"));
+    if (!config || typeof config !== "object" || Array.isArray(config)) return null;
+    if ("disabled" in config && typeof config.disabled !== "boolean") return null;
+    if ("optInOnly" in config && typeof config.optInOnly !== "boolean") return null;
+    if ("optInPaths" in config && (!Array.isArray(config.optInPaths)
+      || config.optInPaths.some((p) => typeof p !== "string" || !p.trim() || !path.isAbsolute(p)))) return null;
+    if ("mapPathToBank" in config && (!config.mapPathToBank || typeof config.mapPathToBank !== "object"
+      || Array.isArray(config.mapPathToBank)
+      || Object.entries(config.mapPathToBank).some(([prefix, bank]) => !prefix.trim() || !path.isAbsolute(prefix)
+        || typeof bank !== "string" || !bank.trim()))) return null;
+    return config;
+  } catch (error) {
+    return error?.code === "ENOENT" ? {} : null;
+  }
+}
+
+export function accessAllowed(cwd, config) {
+  if (!config || typeof cwd !== "string" || !cwd.trim() || !path.isAbsolute(cwd) || config.disabled === true) return false;
+  if (config.optInOnly !== true) return true;
+  const dir = path.resolve(cwd);
+  return (config.optInPaths || []).some((configured) => {
+    const allowed = path.resolve(configured);
+    return dir === allowed || dir.startsWith(`${allowed}${path.sep}`);
+  });
+}
+
+export function currentHome() {
+  return process.env.HOME || os.homedir();
+}

package/cli/coding-agent/agents.mjs

@@ -0,0 +1,34 @@
+/** Supported coding-agent targets for install-coding-agent. */
+
+export const CODING_AGENTS = Object.freeze([
+  { id: "claude-code", label: "Claude Code", hindsightInstall: true },
+  { id: "codex", label: "Codex CLI", hindsightInstall: true },
+  { id: "opencode", label: "OpenCode", hindsightInstall: true },
+  { id: "cursor-cli", label: "Cursor CLI", hindsightInstall: true },
+  {
+    id: "hermes",
+    label: "Hermes",
+    hindsightInstall: false,
+    sessionPath: "Unified openmem MCP (memory_*) or agent-native MCP; no bundled Hermes plugin in this repo.",
+  },
+  {
+    id: "gemini-cli",
+    label: "Gemini CLI",
+    hindsightInstall: false,
+    sessionPath: "Use install-mcp; configure Gemini MCP per Google docs.",
+  },
+  {
+    id: "amp",
+    label: "Amp (Sourcegraph)",
+    hindsightInstall: false,
+    sessionPath: "Unified MCP via install-mcp; follow Amp MCP configuration.",
+  },
+  {
+    id: "cline",
+    label: "Cline",
+    hindsightInstall: false,
+    sessionPath: "Unified MCP in Cursor/VS Code; install-mcp for memory_* tools.",
+  },
+]);
+
+export const DEFAULT_AGENT_IDS = CODING_AGENTS.filter((a) => a.hindsightInstall).map((a) => a.id);