@event4u/agent-config 1.9.1 → 1.13.0

package/scripts/install.py

@@ -223,11 +223,17 @@ def _parse_legacy_settings(text: str) -> "tuple[dict, list]":
     return values, unknown
 
 
+_BARE_ID_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
 def _yaml_scalar(value: str) -> str:
     """Format a string value as a YAML scalar with minimal quoting.
 
-    Booleans and non-negative integers are emitted unquoted; everything
-    else is double-quoted so the migrated file is unambiguous.
+    Booleans and non-negative integers are emitted unquoted. Bare
+    lowercase identifiers (``per_turn``, ``rotate``, ``getters_setters``
+    — the shape of profile values and enum-like strings) are emitted
+    unquoted so `sync_agent_settings.py` stays idempotent against its
+    own output. Everything else is double-quoted.
     """
     if value == "":
         return '""'
@@ -235,6 +241,8 @@ def _yaml_scalar(value: str) -> str:
         return value
     if value.isdigit():
         return value
+    if _BARE_ID_RE.match(value):
+        return value
     # Escape backslashes and double-quotes, then wrap
     escaped = value.replace("\\", "\\\\").replace('"', '\\"')
     return f'"{escaped}"'
@@ -330,6 +338,44 @@ def _migrate_legacy_if_present(project_root: Path, template_body: str) -> "str |
 
 # --- Bridge generators ---
 
+def _parse_profile_ini(path: Path) -> "dict[str, str]":
+    """Parse a simple key=value profile preset (comments start with ; or #)."""
+    values: "dict[str, str]" = {}
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith(";") or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        values[key.strip()] = val.strip()
+    return values
+
+
+_PLACEHOLDER_RE = re.compile(r"__[A-Z][A-Z0-9_]*__")
+
+
+def _render_template(template: str, profile_values: "dict[str, str]") -> str:
+    """Substitute __UPPER_KEY__ placeholders using ini values.
+
+    Each ini key `foo_bar` maps to the `__FOO_BAR__` placeholder. Fails
+    if any placeholder remains unfilled — catches typos and missing
+    profile entries early.
+    """
+    body = template
+    for key, value in profile_values.items():
+        placeholder = f"__{key.upper()}__"
+        if placeholder in body:
+            body = body.replace(placeholder, value)
+    leftover = sorted(set(_PLACEHOLDER_RE.findall(body)))
+    if leftover:
+        fail(
+            "Template has unfilled placeholders after profile render: "
+            + ", ".join(leftover)
+        )
+    return body
+
+
 def ensure_agent_settings(project_root: Path, package_root: Path, profile: str, force: bool) -> None:
     target = project_root / SETTINGS_FILE
     profile_source = package_root / "config" / "profiles" / f"{profile}.ini"
@@ -343,7 +389,13 @@ def ensure_agent_settings(project_root: Path, package_root: Path, profile: str,
     template = template_source.read_text(encoding="utf-8")
     if COST_PROFILE_PLACEHOLDER not in template:
         fail(f"Template is missing placeholder {COST_PROFILE_PLACEHOLDER}")
-    template_body = template.replace(COST_PROFILE_PLACEHOLDER, profile)
+    profile_values = _parse_profile_ini(profile_source)
+    if profile_values.get("cost_profile") != profile:
+        fail(
+            f"Profile preset {profile_source.name} has cost_profile="
+            f"{profile_values.get('cost_profile')!r} but --profile={profile}"
+        )
+    template_body = _render_template(template, profile_values)
 
     legacy_target = project_root / LEGACY_SETTINGS_FILE
     if legacy_target.is_file() and target.exists():

package/scripts/install.sh

@@ -19,7 +19,6 @@ set -euo pipefail
 
 # --- Configuration ---
 COPY_DIRS="rules"  # Subdirectories where files must be real copies (space-separated)
-GITIGNORE_MARKER="# event4u/agent-config"
 
 # Rules that are internal to the agent-config package and should NOT be shipped to consumers.
 # These are only relevant when developing the agent-config package itself.
@@ -35,6 +34,7 @@ TARGET_DIR=""
 DRY_RUN=false
 VERBOSE=false
 QUIET=false
+SKIP_GITIGNORE=false
 
 # --- Logging ---
 log_info()    { $QUIET || echo "  ✅  $*"; }
@@ -51,6 +51,7 @@ parse_args() {
             --dry-run) DRY_RUN=true; shift ;;
             --verbose) VERBOSE=true; shift ;;
             --quiet)   QUIET=true; shift ;;
+            --skip-gitignore) SKIP_GITIGNORE=true; shift ;;
             --help|-h) show_help; exit 0 ;;
             *) log_error "Unknown argument: $1"; show_help; exit 1 ;;
         esac
@@ -103,6 +104,7 @@ Options:
   --dry-run        Show what would happen without making changes
   --verbose        Show detailed output
   --quiet          Suppress all output except errors
+  --skip-gitignore Do not touch the target project's .gitignore
   --help, -h       Show this help
 
 Environment:
@@ -561,39 +563,63 @@ copy_if_missing() {
     cp "$source" "$target"
 }
 
-# Ensure .gitignore contains agent-config entries
+# Ensure .gitignore contains the managed agent-config block.
+# Delegates to scripts/sync_gitignore.py so the installer and the
+# standalone /sync-gitignore command share one source of truth
+# (config/gitignore-block.txt). Honors --dry-run and --skip-gitignore.
 ensure_gitignore() {
     local project_root="$1"
     local gitignore="$project_root/.gitignore"
+    local sync_script="$SOURCE_DIR/scripts/sync_gitignore.py"
+    local template="$SOURCE_DIR/config/gitignore-block.txt"
 
+    if $SKIP_GITIGNORE; then
+        log_verbose "skip .gitignore (--skip-gitignore)"
+        return 0
+    fi
+
+    # Match the pre-refactor behavior: don't create .gitignore in a
+    # project that doesn't use git / doesn't already have one.
     if [[ ! -f "$gitignore" ]]; then
         return 0
     fi
 
-    if grep -qF "$GITIGNORE_MARKER" "$gitignore"; then
-        return 0  # Already present
+    if [[ ! -f "$sync_script" || ! -f "$template" ]]; then
+        log_warn ".gitignore sync skipped — script or template missing"
+        return 0
+    fi
+
+    local args=(--path "$gitignore" --template "$template" --quiet)
+    $DRY_RUN && args+=(--dry-run)
+
+    if python3 "$sync_script" "${args[@]}" >/dev/null 2>&1; then
+        log_verbose ".gitignore synced"
+    else
+        log_warn ".gitignore sync failed (exit $?)"
+    fi
+}
+
+# Install the consumer-facing CLI wrapper `./agent-config` at the project
+# root. Gitignored, overwritten on every install, delegates to the master
+# CLI shipped in the package (node_modules or vendor).
+install_cli_wrapper() {
+    local project_root="$1"
+    local template="$SOURCE_DIR/templates/agent-config-wrapper.sh"
+    local target="$project_root/agent-config"
+
+    if [[ ! -f "$template" ]]; then
+        log_verbose "CLI wrapper template missing: $template — skipping"
+        return 0
     fi
 
     if $DRY_RUN; then
-        log_verbose "append .gitignore block"
+        log_verbose "install CLI wrapper → $target"
         return
     fi
 
-    cat >> "$gitignore" << 'BLOCK'
-
-# event4u/agent-config
-# Agent config — symlinked from vendor (auto-managed)
-.augment/skills/
-.augment/commands/
-.augment/guidelines/
-.augment/templates/
-.augment/contexts/
-.augment/scripts/
-.augment/README.md
-
-# Agent config — NOT ignored (real copies, may contain project overrides)
-# .augment/rules/
-BLOCK
+    cp "$template" "$target"
+    chmod +x "$target"
+    log_info "Installed ./agent-config wrapper"
 }
 
 # --- Main ---
@@ -626,7 +652,10 @@ main() {
     generate_windsurfrules "$TARGET_DIR"
     create_gemini_md "$TARGET_DIR"
 
-    # 5. Manage .gitignore
+    # 5. Install consumer CLI wrapper (gitignored, overwritten on every install)
+    install_cli_wrapper "$TARGET_DIR"
+
+    # 6. Manage .gitignore
     ensure_gitignore "$TARGET_DIR"
 
     echo ""

package/scripts/mcp_render.py

@@ -31,16 +31,23 @@ import sys
 from pathlib import Path
 from typing import Any
 
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
-SOURCE_FILE = PROJECT_ROOT / "mcp.json"
-
 ENV_PLACEHOLDER = re.compile(r"\$\{env:([^}]+)\}")
 
-# In-project targets. Claude Desktop is user-scope, opt-in via --claude-desktop.
-IN_PROJECT_TARGETS: dict[str, Path] = {
-    "cursor": PROJECT_ROOT / ".cursor" / "mcp.json",
-    "windsurf": PROJECT_ROOT / ".windsurf" / "mcp.json",
-}
+# Project root defaults to the current working directory so the renderer
+# works both for package maintainers (running from the package root via
+# Taskfile) and for consumer projects (running via `./agent-config
+# mcp:render` from their own repo root). Override with --project-root.
+def default_project_root() -> Path:
+    return Path.cwd().resolve()
+
+
+def in_project_targets(project_root: Path) -> dict[str, Path]:
+    return {
+        "cursor": project_root / ".cursor" / "mcp.json",
+        "windsurf": project_root / ".windsurf" / "mcp.json",
+    }
+
+
 CLAUDE_DESKTOP_TARGET = Path.home() / ".config" / "claude-desktop" / "claude_desktop_config.json"
 
 
@@ -104,20 +111,25 @@ def write_target(path: Path, content: dict[str, Any]) -> None:
     path.write_text(serialized, encoding="utf-8")
 
 
-def collect_targets(include_claude_desktop: bool) -> dict[str, Path]:
-    targets = dict(IN_PROJECT_TARGETS)
+def collect_targets(project_root: Path, include_claude_desktop: bool) -> dict[str, Path]:
+    targets = dict(in_project_targets(project_root))
     if include_claude_desktop:
         targets["claude-desktop"] = CLAUDE_DESKTOP_TARGET
     return targets
 
 
+def resolve_source(args: argparse.Namespace, project_root: Path) -> Path:
+    return Path(args.source) if args.source else project_root / "mcp.json"
+
+
 def cmd_render(args: argparse.Namespace) -> int:
-    data = load_source(Path(args.source))
+    project_root = Path(args.project_root).resolve() if args.project_root else default_project_root()
+    data = load_source(resolve_source(args, project_root))
     rendered, missing = render(data)
     if missing:
         print(format_missing_report(missing), file=sys.stderr)
         return 1
-    targets = collect_targets(args.claude_desktop)
+    targets = collect_targets(project_root, args.claude_desktop)
     for name, path in targets.items():
         write_target(path, rendered)
         print(f"✅  {name:16} → {path}")
@@ -125,20 +137,21 @@ def cmd_render(args: argparse.Namespace) -> int:
 
 
 def cmd_check(args: argparse.Namespace) -> int:
-    data = load_source(Path(args.source))
+    project_root = Path(args.project_root).resolve() if args.project_root else default_project_root()
+    data = load_source(resolve_source(args, project_root))
     rendered, missing = render(data)
     if missing:
         print(format_missing_report(missing), file=sys.stderr)
         return 1
     serialized = json.dumps(rendered, indent=2, sort_keys=True) + "\n"
-    targets = collect_targets(args.claude_desktop)
+    targets = collect_targets(project_root, args.claude_desktop)
     diffs = []
     for name, path in targets.items():
         actual = path.read_text(encoding="utf-8") if path.exists() else ""
         if actual != serialized:
             diffs.append((name, path))
     if diffs:
-        print("❌  Targets out of date (run `task mcp:render`):", file=sys.stderr)
+        print("❌  Targets out of date (run `./agent-config mcp:render`):", file=sys.stderr)
         for name, path in diffs:
             print(f"  - {name}: {path}", file=sys.stderr)
         return 1
@@ -148,7 +161,8 @@ def cmd_check(args: argparse.Namespace) -> int:
 
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="Render mcp.json → per-tool config files.")
-    parser.add_argument("--source", default=str(SOURCE_FILE), help="Source mcp.json (default: repo root)")
+    parser.add_argument("--source", default=None, help="Source mcp.json (default: <project-root>/mcp.json)")
+    parser.add_argument("--project-root", default=None, help="Project root for resolving source and targets (default: CWD)")
     parser.add_argument("--claude-desktop", action="store_true", help="Also write Claude Desktop user-scope config")
     parser.add_argument("--check", action="store_true", help="Dry-run; exit non-zero if targets are stale")
     args = parser.parse_args(argv)

package/scripts/memory_lookup.py

@@ -1,21 +1,28 @@
 #!/usr/bin/env python3
-"""File-based retrieval for the `absent` path.
+"""Hybrid retrieval — file-first with optional package augmentation.
 
 Implements the shared `retrieve(types, keys, limit)` abstraction used
 by skills. Reads YAML under `agents/memory/<type>/` (curated, hand-
 reviewed) and JSONL under `agents/memory/intake/*.jsonl` (agent-written,
 append-only, supersede-chain aware).
 
-The returned shape is identical to the `present`-path adapter over the
-`@event4u/agent-memory` API, so skills stay backend-agnostic.
+When the `@event4u/agent-memory` package is present (see
+`scripts/memory_status.py`), callers can pass the result of
+:func:`package_operational_provider` to route additional retrieval
+through the package's semantic CLI. Repo entries always win on
+conflict — see `_apply_conflict_rule`.
 
 Usage:
     python3 scripts/memory_lookup.py --types domain-invariants,ownership \\
         --key "app/Http/Controllers/Foo" --limit 5
     python3 scripts/memory_lookup.py --types incident-learnings --format json
+    python3 scripts/memory_lookup.py --types ownership --key billing --auto
 
-    from scripts.memory_lookup import retrieve
-    hits = retrieve(types=["ownership"], keys=["app/Http"], limit=3)
+    from scripts.memory_lookup import retrieve, package_operational_provider
+    hits = retrieve(
+        types=["ownership"], keys=["app/Http"], limit=3,
+        operational_provider=package_operational_provider(),
+    )
 """
 
 from __future__ import annotations
@@ -23,6 +30,8 @@ from __future__ import annotations
 import argparse
 import fnmatch
 import json
+import os
+import subprocess
 import sys
 from dataclasses import dataclass, asdict, field
 from pathlib import Path
@@ -229,6 +238,125 @@ def _apply_conflict_rule(
     return merged, shadows
 
 
+# ---------------------------------------------------------------------------
+# Package-backed operational provider (the `present` path)
+# ---------------------------------------------------------------------------
+#
+# When `memory_status.status() == "present"` the consumer-facing contract
+# says retrieval should route through `@event4u/agent-memory`. The package
+# CLI is purely **semantic** (`memory retrieve <query> --type T …`); the
+# shared `retrieve(types, keys, …)` API is **key-based**. The hybrid
+# resolution agreed in `agents/contexts/agent-memory-contract.md` synthesises
+# `keys` into a single natural-language query for the package call, while
+# the file fallback continues to do glob/substring matching on the same
+# keys. Both legs land in the same `Hit` shape so the conflict rule can
+# merge them transparently.
+
+_CLI_TIMEOUT_SECONDS = 5.0
+_CLI_RETRIEVE_LIMIT_DEFAULT = 20
+
+
+def _synthesize_query(keys: list[str]) -> str:
+    """Turn a list of retrieval keys into one natural-language query.
+
+    Keys are typically file paths (`app/Http/Controllers/Foo`), feature
+    names (`billing`), or short identifiers — joining them with spaces
+    gives the package's semantic search enough surface to score against
+    without inventing structure. Empty or whitespace-only keys are
+    dropped; if nothing remains the caller falls back to the file path.
+    """
+    cleaned = [k.strip() for k in keys if isinstance(k, str) and k.strip()]
+    return " ".join(cleaned)
+
+
+def _cli_operational_provider(
+    types: list[str],
+    keys: list[str],
+    *,
+    cli_path: str = "memory",
+    timeout: float = _CLI_TIMEOUT_SECONDS,
+    limit: int = _CLI_RETRIEVE_LIMIT_DEFAULT,
+) -> Iterable[Hit]:
+    """Run `memory retrieve` and yield operational `Hit` objects.
+
+    Pino structured logs from the package go to stderr; stdout is a
+    clean v1 retrieval envelope. Any non-zero exit, timeout, or parse
+    failure degrades to "no operational hits" — `retrieve()` already
+    treats provider exceptions as a soft warning, so the caller still
+    gets the file-fallback result.
+    """
+    query = _synthesize_query(keys)
+    if not query:
+        return
+    cmd: list[str] = [cli_path, "retrieve", query, "--limit", str(limit)]
+    for t in types:
+        cmd.extend(["--type", t])
+    try:
+        out = subprocess.run(
+            cmd,
+            capture_output=True, text=True, timeout=timeout,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return
+    if out.returncode != 0:
+        return
+    try:
+        envelope = json.loads(out.stdout)
+    except (ValueError, TypeError):
+        return
+    entries = envelope.get("entries") if isinstance(envelope, dict) else None
+    if not isinstance(entries, list):
+        return
+    for e in entries:
+        if not isinstance(e, dict):
+            continue
+        eid = e.get("id")
+        etype = e.get("type")
+        if not isinstance(eid, str) or not isinstance(etype, str):
+            continue
+        # The package returns `confidence` (0..1) per the v1 envelope;
+        # map it onto our internal `score` field so the conflict rule
+        # and ranking work uniformly across providers.
+        try:
+            score = float(e.get("confidence", 0.0))
+        except (TypeError, ValueError):
+            score = 0.0
+        body = e.get("body") if isinstance(e.get("body"), dict) else {}
+        yield Hit(
+            id=eid,
+            type=etype,
+            source="operational",
+            path=f"agent-memory:{eid}",
+            score=score,
+            entry=body,
+        )
+
+
+def package_operational_provider() -> Optional[OperationalProvider]:
+    """Return a CLI-backed provider when the package is `present`, else None.
+
+    Callers who want automatic backend routing pass the result directly
+    to :func:`retrieve` — `None` is a safe value that yields file-only
+    retrieval, so this is the recommended one-liner for skills:
+
+        retrieve(types, keys, operational_provider=package_operational_provider())
+
+    The status probe is bounded (≤ 2s, cached per process) — see
+    `scripts/memory_status.py`. We import lazily so pure file-fallback
+    callers never pay for the probe.
+    """
+    # Late import: keeps `memory_lookup` importable even when
+    # `memory_status` is missing in stripped consumer installs.
+    try:
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import memory_status  # type: ignore[import-not-found]
+    except ImportError:
+        return None
+    if memory_status.status().status != "present":
+        return None
+    return _cli_operational_provider
+
+
 def retrieve(
     types: list[str],
     keys: list[str],
@@ -402,16 +530,24 @@ def main() -> int:
     ap.add_argument("--with-shadows", action="store_true",
                     help="Include shadowed-operational entries in the output "
                          "(no-op until an operational backend is wired)")
+    ap.add_argument("--auto", action="store_true",
+                    help="Auto-route to the @event4u/agent-memory package "
+                         "when memory_status.status() == 'present'; "
+                         "falls through to file-only retrieval otherwise")
     args = ap.parse_args()
     types = [t.strip() for t in args.types.split(",") if t.strip()]
     if not types:
         print("error: --types is required", file=sys.stderr)
         return 2
+    op_provider = package_operational_provider() if args.auto else None
     if args.envelope == "v1":
-        envelope = retrieve_v1(types, args.key, args.limit)
+        envelope = retrieve_v1(types, args.key, args.limit,
+                               operational_provider=op_provider)
         print(json.dumps(envelope, indent=2, default=str))
         return 0
-    result = retrieve(types, args.key, args.limit, with_shadows=args.with_shadows)
+    result = retrieve(types, args.key, args.limit,
+                      operational_provider=op_provider,
+                      with_shadows=args.with_shadows)
     if args.with_shadows:
         assert isinstance(result, RetrievalResult)
         hits, shadows = result.hits, result.shadows

package/scripts/memory_status.py

@@ -35,7 +35,7 @@ from typing import Literal
 
 Status = Literal["absent", "misconfigured", "present"]
 
-_CLI_CANDIDATES = ("agent-memory", "agentmem")
+_CLI_CANDIDATES = ("memory", "agent-memory", "agentmem")
 _HEALTH_TIMEOUT_SECONDS = 2.0
 _CACHE_ENV = "AGENT_MEMORY_STATUS"
 _CACHE_FILE = Path(".agent-memory") / "status.cache"
@@ -54,6 +54,11 @@ class Result:
     reason: str             # short explanation
     elapsed_ms: int         # time spent probing (0 if cached)
     cli_path: str = ""      # resolved CLI path, if any
+    # Populated only when status == "present" — sourced from the
+    # `health` CLI envelope so the v1 health() reports real package
+    # capabilities instead of file-fallback placeholders.
+    backend_version: str = ""
+    features: tuple = ()
 
 
 def _find_cli() -> str:
@@ -64,8 +69,45 @@ def _find_cli() -> str:
     return ""
 
 
-def _probe_health(cli_path: str) -> tuple[bool, str]:
-    """Returns (healthy, reason)."""
+def _parse_health_envelope(stdout: str) -> dict | None:
+    """Extract the v1 health envelope from `memory health` stdout.
+
+    The package emits a single JSON object on stdout (pino structured
+    logs go to stderr). We tolerate older builds that may have leaked
+    log lines into stdout by scanning for the first top-level object
+    that carries ``contract_version``.
+    """
+    text = (stdout or "").strip()
+    if not text:
+        return None
+    try:
+        obj = json.loads(text)
+    except ValueError:
+        obj = None
+    if isinstance(obj, dict) and obj.get("contract_version"):
+        return obj
+    # Fallback: line-by-line scan for an envelope-shaped object — covers
+    # the case where structured logs accidentally share stdout.
+    for line in text.splitlines():
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            cand = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(cand, dict) and cand.get("contract_version"):
+            return cand
+    return None
+
+
+def _probe_health(cli_path: str) -> tuple[bool, str, dict | None]:
+    """Returns (healthy, reason, envelope).
+
+    On success ``envelope`` is the parsed v1 health envelope (may still
+    be ``None`` for very old CLIs that don't emit one). On failure it
+    is always ``None``.
+    """
     try:
         out = subprocess.run(
             [cli_path, "health"],
@@ -73,15 +115,16 @@ def _probe_health(cli_path: str) -> tuple[bool, str]:
             timeout=_HEALTH_TIMEOUT_SECONDS,
         )
     except subprocess.TimeoutExpired:
-        return False, f"health() timed out after {_HEALTH_TIMEOUT_SECONDS}s"
+        return False, f"health() timed out after {_HEALTH_TIMEOUT_SECONDS}s", None
     except FileNotFoundError:
-        return False, "CLI vanished between which() and invoke"
+        return False, "CLI vanished between which() and invoke", None
     if out.returncode != 0:
         # First line of combined output, capped, for the reason field.
         msg = (out.stderr or out.stdout or "exit != 0").strip().splitlines()
         head = msg[0][:120] if msg else "exit != 0"
-        return False, f"health() returned {out.returncode}: {head}"
-    return True, "ok"
+        return False, f"health() returned {out.returncode}: {head}", None
+    envelope = _parse_health_envelope(out.stdout)
+    return True, "ok", envelope
 
 
 def _read_cache() -> Result | None:
@@ -131,10 +174,23 @@ def status(refresh: bool = False) -> Result:
         result = Result("absent", "file",
                         "agent-memory CLI not on PATH", 0)
     else:
-        healthy, reason = _probe_health(cli)
+        healthy, reason, envelope = _probe_health(cli)
         elapsed = int((time.monotonic() - t0) * 1000)
         if healthy:
-            result = Result("present", "package", reason, elapsed, cli)
+            backend_version = ""
+            features: tuple = ()
+            if isinstance(envelope, dict):
+                bv = envelope.get("backend_version")
+                if isinstance(bv, str):
+                    backend_version = bv
+                feats = envelope.get("features")
+                if isinstance(feats, list) and all(
+                    isinstance(f, str) for f in feats
+                ):
+                    features = tuple(feats)
+            result = Result("present", "package", reason, elapsed, cli,
+                            backend_version=backend_version,
+                            features=features)
         else:
             result = Result("misconfigured", "file", reason, elapsed, cli)
     _write_cache(result)
@@ -148,6 +204,11 @@ def health(refresh: bool = False) -> dict:
     Maps the three-state :func:`status` result onto the contract's
     ``ok | degraded | error`` so consumers can read
     ``contract_version`` without caring about the file-vs-package split.
+
+    When the package backs the call (``status == "present"``), the
+    envelope reports the package's own ``backend_version`` and
+    ``features`` so consumers can feature-detect against real
+    capabilities. Otherwise the file-fallback markers are returned.
     """
     r = status(refresh=refresh)
     envelope_status = {
@@ -155,11 +216,12 @@ def health(refresh: bool = False) -> dict:
         "misconfigured": "degraded",
         "absent": "ok",
     }[r.status]
-    # When the package is present, report its version from `health()`
-    # output; until we parse that, keep the file-fallback marker so the
-    # envelope never lies about what backed the response.
-    backend_version = _FILE_BACKEND_VERSION
-    features = list(_FILE_BACKEND_FEATURES)
+    if r.status == "present" and (r.backend_version or r.features):
+        backend_version = r.backend_version or _FILE_BACKEND_VERSION
+        features = list(r.features) if r.features else list(_FILE_BACKEND_FEATURES)
+    else:
+        backend_version = _FILE_BACKEND_VERSION
+        features = list(_FILE_BACKEND_FEATURES)
     return {
         "contract_version": CONTRACT_VERSION,
         "status": envelope_status,

package/scripts/postinstall.sh

@@ -33,6 +33,22 @@ trap 'rm -f "$LOG"' EXIT
 bash "$INSTALLER" --quiet >"$LOG" 2>&1
 CODE=$?
 if [[ $CODE -eq 0 ]]; then
+    # Optional companion: @event4u/agent-memory. Suggest it once, only if
+    # the consumer hasn't already installed it (locally or on PATH). The
+    # hint is purely informational; agent-config falls back to file-based
+    # memory when the backend is absent.
+    if ! command -v memory >/dev/null 2>&1 \
+       && ! command -v agent-memory >/dev/null 2>&1 \
+       && [[ ! -d "$SCRIPT_DIR/../../@event4u/agent-memory" ]]; then
+        cat >&2 <<'HINT'
+💡 agent-config tip: install @event4u/agent-memory for persistent agent
+   learnings across sessions (optional, dev-only):
+
+       npm install --save-dev @event4u/agent-memory
+
+   Skip if you don't need it — agent-config falls back to file-based memory.
+HINT
+    fi
     exit 0
 fi