forget-connect 0.4.0 → 0.5.1

package/README.md

@@ -8,9 +8,13 @@ overwriting the MCP servers or global instructions you already have.
 npx forget-connect
 ```
 
-By default this targets the local server at `http://localhost:8000/mcp` —
-your memories stay on your machine. The guided flow detects installed
-clients and then:
+By default this targets the local server at `http://localhost:8000` and
+scopes each client to its own memory pool at
+`/mcp/<client>/http/<os-username>` (for example
+`/mcp/claude-code/http/junghun`) — your memories stay on your machine and
+stay isolated per user and per client. Pass `--no-scope` for the shared
+unscoped `/mcp` endpoint. The guided flow detects installed clients and
+then:
 
 - merges a `forget` entry into each selected MCP config;
 - installs a marked memory rule in Claude Code's `CLAUDE.md` and Codex's
@@ -73,10 +77,11 @@ block. It does not restore backups or remove unrelated config.
 
 ```text
 --client <ids>       claude-code,codex,claude-desktop,all
---url <url>          MCP URL (default: http://localhost:8000/mcp)
+--url <url>          Exact MCP URL to install (default base: http://localhost:8000/mcp)
 --hosted             Use the managed Forget service (legacy)
 --user-id <id>       Memory user scope; pair with --app-id
 --app-id <id>        Project/app scope; pair with --user-id
+--no-scope           Install the shared unscoped /mcp endpoint (legacy behavior)
 --no-auth            Do not install a Bearer token
 --no-rules           Do not manage CLAUDE.md or AGENTS.md
 --no-migrate-enacta  Keep matching legacy config and rule blocks

package/assets/hooks/forget_capture.py

@@ -21,6 +21,10 @@ import re
 import sys
 import urllib.request
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from forget_project import project_key_for_path, scope_disabled  # noqa: E402
+
 FORGET_URL = os.environ.get("FORGET_MCP_URL", "http://127.0.0.1:8000/mcp")
 STATE_DIR = os.path.expanduser("~/.forget/hooks/state")
 TAIL_BYTES = 400_000
@@ -111,20 +115,19 @@ def _capture(hook_input: dict, digest: dict, transcript_path: str, session_id: s
         f"{' (꼬리 표본)' if digest['tail_only'] else ''}, {digest['first_ts']}~{digest['last_ts']}. "
         f"최근 사용자 발화: {snippets}. 전문: {transcript_path}"
     )
-    _rpc(
-        "add_memory",
-        {
-            "text": text,
-            "infer": False,
-            "source_role": "tool",
-            "metadata": {
-                "hook": event,
-                "session_id": session_id,
-                "transcript_path": transcript_path,
-                "trigger": label,
-            },
-        },
-    )
+    metadata = {
+        "hook": event,
+        "session_id": session_id,
+        "transcript_path": transcript_path,
+        "trigger": label,
+    }
+    # A session pointer belongs to the repo the session happened in — the one
+    # write here whose layer needs no guessing.
+    project = None if scope_disabled() else project_key_for_path(hook_input.get("cwd") or os.getcwd())
+    if project:
+        metadata["project"] = project
+        metadata["scope_layer"] = "project"
+    _rpc("add_memory", {"text": text, "infer": False, "source_role": "tool", "metadata": metadata})
 
 
 def _handoff(digest: dict, transcript_path: str, session_id: str) -> None:

package/assets/hooks/forget_project.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""Project identity for hooks: which repo is this session working in?
+
+Design principle (2026-08-01): a scope the user has to declare is a scope that
+fails. Our two worst scope bugs were fragmentation (one topic scattered across
+five pools, so search missed it) and contamination (339 demo rows living
+alongside live memory, F4). Asking the user to create and select a project
+scope hands both diseases to the user. So the boundary is DETECTED, never
+configured — every hook already receives `cwd`, and the git repository root is
+the project.
+
+Layering, not splitting: one store, two layers distinguished by metadata.
+Splitting into separate pools would re-introduce fragmentation by construction.
+
+- metadata.project     — origin key, always attached on write (provenance)
+- metadata.scope_layer — "global" | "project" (which layer recall reads)
+
+Recall then reads: this project's rows + everything global + everything
+untagged. Untagged-means-global is what keeps every pre-existing memory
+visible, so turning this on changes nothing until new writes land.
+
+Stdlib only, and no imports from the `forget` package: the hooks are deployed
+as standalone scripts under ~/.forget/hooks/ and run with the system python.
+"""
+
+from __future__ import annotations
+
+import configparser
+import json
+import os
+import re
+
+CONFIG_PATH = os.path.expanduser("~/.forget/projects.json")
+KEY_MAX_LEN = 40
+
+# Directories that hold projects instead of being one. Keying off them would
+# file unrelated work under "documents" — fragmentation's other direction.
+_CONTAINER_NAMES = {
+    "code",
+    "desktop",
+    "dev",
+    "documents",
+    "downloads",
+    "git",
+    "projects",
+    "repos",
+    "src",
+    "tmp",
+    "work",
+    "workspaces",
+}
+
+# Crude v1 classifier (same spirit as the mechanical-echo-v1 outcome labeler:
+# its job is to start the flywheel, not to be right). A fact about the user
+# themself outlives any single repo; everything else stays with its repo.
+# The default is deliberately "project": global contamination costs more than
+# a project-local miss, and the miss is recoverable by asking across projects.
+_GLOBAL_PATTERNS = (
+    r"(?:나는|내가|제가|정훈은|정훈이|사용자는|유저는)[^.\n]{0,40}"
+    r"(?:선호|좋아|싫어|원해|원한다|스타일|성향|습관|정체성|목표|철학)",
+    r"\b(?:i|my)\b[^.\n]{0,40}\b(?:prefer|preference|always|never|habit|style|identity)\b",
+    r"(?:모든 프로젝트|어느 프로젝트|어디서나|프로젝트 무관|전역|전체적으로)",
+    r"\b(?:globally|(?:across|all|every) projects?\b|across (?:all )?projects|regardless of (?:the )?project)\b",
+)
+
+# "이 레포는 내가 선호하는 패턴대로" — the sentence is ABOUT the repo even
+# though it name-drops a preference. Repo-context anchors outrank user-pattern
+# hits: a fact anchored to "this repo" belongs to it.
+_REPO_ANCHOR_PATTERNS = (
+    r"이 (?:레포|저장소|프로젝트|코드베이스)",
+    r"\bthis (?:repo|repository|project|codebase)\b",
+)
+
+# Explicit permission to cross the boundary. Recall stays inside the current
+# project unless the user asks to look elsewhere — the boundary doubles as a
+# privacy gate (the other company's strategy must not leak into this session's
+# capsule), so crossing has to be asked for, and is flagged when it happens.
+_CROSS_PROJECT_PATTERNS = (
+    r"다른 (?:프로젝트|레포|repo|회사)",
+    # Plural or explicitly-universal only: "프로젝트 전체 테스트 돌려줘" means
+    # THIS project entire, and loosening the boundary on it would be a leak.
+    r"프로젝트들",
+    r"(?:모든|전체) 프로젝트(?:들)?",
+    r"프로젝트(?:들)? ?(?:통틀어|건너|넘어)",
+    r"(?:다른 곳|딴 데|저쪽)에서",
+    r"\b(?:other|another|across|all) (?:projects|repos|repositories)\b",
+    r"\b(?:other|another) (?:project|repo)\b",
+    r"\bany project\b",
+)
+
+
+def _config() -> dict:
+    """Optional overrides: {"aliases": {...}, "ignore": [...]}.
+
+    The escape hatch for the one case detection cannot resolve on its own —
+    two repositories that share a name. Nobody needs to write this file for
+    the common case.
+    """
+    try:
+        with open(CONFIG_PATH, encoding="utf-8") as fh:
+            config = json.load(fh)
+        return config if isinstance(config, dict) else {}
+    except Exception:
+        return {}
+
+
+def _slug(raw: str) -> str:
+    """Readable, stable key. Unicode word chars survive — a Korean directory
+    name is a perfectly good key, and transliterating would only obscure it."""
+    slug = re.sub(r"[^\w.-]+", "-", str(raw).strip(), flags=re.UNICODE).strip("-._")
+    return slug.lower()[:KEY_MAX_LEN]
+
+
+def _git_common_dir(start: str) -> str | None:
+    """The shared .git of the repo containing `start`, worktrees included.
+
+    The worktree case is the trap: this very session runs in an Orca worktree
+    whose directory is named after a throwaway branch topic, while the same
+    repo is also checked out at ~/Documents/forget. Keying off the worktree
+    directory would file the same project under two keys — fragmentation
+    again. Resolving to the common .git collapses them.
+    """
+    current = os.path.realpath(start)
+    while True:
+        candidate = os.path.join(current, ".git")
+        if os.path.isdir(candidate):
+            return candidate
+        if os.path.isfile(candidate):
+            try:
+                with open(candidate, encoding="utf-8") as fh:
+                    pointer = fh.read().strip()
+            except OSError:
+                return None
+            if pointer.startswith("gitdir:"):
+                path = pointer.split(":", 1)[1].strip()
+                if not os.path.isabs(path):
+                    path = os.path.join(current, path)
+                path = os.path.realpath(path)
+                marker = os.sep + "worktrees" + os.sep
+                if marker in path:
+                    path = path.split(marker)[0]
+                return path
+            return None
+        parent = os.path.dirname(current)
+        if parent == current:
+            return None
+        current = parent
+
+
+def _origin_url(common_dir: str) -> str:
+    parser = configparser.ConfigParser(strict=False)
+    try:
+        parser.read(os.path.join(common_dir, "config"), encoding="utf-8")
+    except Exception:
+        return ""
+    for section in ('remote "origin"', "remote origin"):
+        if parser.has_option(section, "url"):
+            return str(parser.get(section, "url") or "").strip()
+    return ""
+
+
+def repo_identity(url: str) -> str:
+    """github.com/owner/repo, scheme- and suffix-free, for alias lookups."""
+    identity = re.sub(r"^[a-z+]+://", "", url.strip(), flags=re.IGNORECASE)
+    identity = re.sub(r"^[^/@]+@", "", identity)  # git@host:owner/repo
+    identity = identity.replace(":", "/", 1) if "/" not in identity.split(":")[0] else identity
+    identity = re.sub(r"\.git/?$", "", identity).rstrip("/")
+    return identity.lower()
+
+
+def project_key_for_path(path: str | None) -> str | None:
+    """The project key for a working directory, or None for "no project".
+
+    None means global-only: a session started in $HOME or some scratch
+    directory has no project to be about, and inventing one there would
+    scatter memories across as many keys as the user has stray folders.
+    """
+    if not path:
+        return None
+    real = os.path.realpath(path)
+    config = _config()
+    aliases = config.get("aliases") if isinstance(config.get("aliases"), dict) else {}
+    ignore = {str(item).lower() for item in (config.get("ignore") or []) if str(item)}
+
+    common_dir = _git_common_dir(real)
+    identity = ""
+    if common_dir:
+        identity = repo_identity(_origin_url(common_dir))
+        if identity:
+            raw = identity.rsplit("/", 1)[-1]
+        else:
+            # No remote: the repo directory itself names the project. Use the
+            # common .git's parent, not cwd — same worktree reason as above.
+            repo_root = os.path.dirname(common_dir.rstrip(os.sep))
+            raw = os.path.basename(repo_root)
+    else:
+        if real in (os.path.realpath(os.path.expanduser("~")), os.sep):
+            return None
+        raw = os.path.basename(real)
+        if raw.lower() in _CONTAINER_NAMES:
+            return None
+
+    for candidate in (identity, raw):
+        if candidate and str(aliases.get(candidate) or "").strip():
+            return _slug(aliases[candidate])
+    key = _slug(raw)
+    if not key or key in ignore:
+        return None
+    return key
+
+
+def layered_filter(project_key: str | None) -> dict | None:
+    """Recall filter: this project + the global layer + everything untagged."""
+    if not project_key:
+        return None
+    return {
+        "OR": [
+            {"metadata.project": project_key},
+            {"metadata.project": None},  # written before layering existed
+            {"metadata.scope_layer": "global"},
+        ]
+    }
+
+
+def classify_layer(text: str) -> str:
+    """"global" for facts about the user themself, else "project"."""
+    body = str(text or "")
+    for anchor in _REPO_ANCHOR_PATTERNS:
+        if re.search(anchor, body, flags=re.IGNORECASE | re.UNICODE):
+            return "project"
+    for pattern in _GLOBAL_PATTERNS:
+        if re.search(pattern, body, flags=re.IGNORECASE | re.UNICODE):
+            return "global"
+    return "project"
+
+
+def wants_cross_project(prompt: str) -> bool:
+    body = str(prompt or "")
+    return any(re.search(p, body, flags=re.IGNORECASE | re.UNICODE) for p in _CROSS_PROJECT_PATTERNS)
+
+
+def scope_disabled() -> bool:
+    return str(os.environ.get("FORGET_PROJECT_SCOPE", "")).strip().lower() in {"0", "off", "false"}

package/assets/hooks/forget_projecttag.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: stamp the originating project onto every memory write.
+
+The write side of project layering. The recall side can filter by
+metadata.project only if something puts it there, and the one thing that
+knows which repo a session is working in is the hook — the forget server is a
+shared local daemon with no idea of any client's cwd, and asking the agent to
+remember to pass a project key would make correctness depend on the model's
+diligence (and on the user configuring scopes, which is the failure this whole
+design exists to avoid).
+
+So the tag is attached mechanically, by rewriting the tool input in flight
+(`updatedInput`). No permissionDecision is returned: the hook adds provenance,
+it does not decide whether a write is allowed.
+
+add_memory writes get metadata.project + scope_layer; record_task_state gets
+a top-level project key (the task ledger stores it in its scope blob — this
+is the F2 cure: heartbeat/Quant task rows stop invading the devloop capsule).
+add_memories stays untagged: it takes no metadata over MCP.
+
+Fail-open: on any error, print nothing and exit 0 — the write proceeds
+untagged, which recall reads as the global layer.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from forget_project import classify_layer, project_key_for_path, scope_disabled  # noqa: E402
+
+MEMORY_TOOLS = {"mcp__forget__add_memory", "add_memory"}
+TASK_TOOLS = {"mcp__forget__record_task_state", "record_task_state"}
+TAGGED_TOOLS = MEMORY_TOOLS | TASK_TOOLS
+TAGGER_VERSION = "cwd-git-v1"
+
+
+def _write_text(tool_input: dict) -> str:
+    """What the classifier reads: the fact being saved, however it arrived."""
+    text = str(tool_input.get("text") or "")
+    if text:
+        return text
+    messages = tool_input.get("messages")
+    if isinstance(messages, list):
+        parts = [str(m.get("content") or "") for m in messages if isinstance(m, dict)]
+        return " ".join(part for part in parts if part)
+    return ""
+
+
+def _emit(updated_input: dict) -> None:
+    print(
+        json.dumps(
+            {"hookSpecificOutput": {"hookEventName": "PreToolUse", "updatedInput": updated_input}},
+            ensure_ascii=False,
+        )
+    )
+
+
+def main() -> None:
+    hook_input = json.load(sys.stdin)
+    tool_name = str(hook_input.get("tool_name") or "")
+    if tool_name not in TAGGED_TOOLS:
+        return
+    if scope_disabled():
+        return
+    tool_input = hook_input.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return
+    project = project_key_for_path(hook_input.get("cwd") or os.getcwd())
+    if not project:
+        return  # no project to be about → leave it in the global layer
+
+    if tool_name in TASK_TOOLS:
+        # A task is inherently project work — no layer to classify. The key
+        # rides top-level; the server files it into the task's scope blob.
+        if tool_input.get("project"):
+            return  # an explicit caller outranks detection
+        _emit({**tool_input, "project": project})
+        return
+
+    metadata = tool_input.get("metadata")
+    metadata = dict(metadata) if isinstance(metadata, dict) else {}
+    if metadata.get("project"):
+        return  # an explicit caller outranks detection
+    metadata["project"] = project
+    metadata.setdefault("scope_layer", classify_layer(_write_text(tool_input)))
+    metadata.setdefault("project_tagger", TAGGER_VERSION)
+    _emit({**tool_input, "metadata": metadata})
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass
+    sys.exit(0)

package/assets/hooks/forget_sessionstart.py

@@ -16,10 +16,50 @@ import sys
 import time
 import urllib.request
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from forget_project import layered_filter, project_key_for_path, scope_disabled  # noqa: E402
+
 FORGET_URL = os.environ.get("FORGET_MCP_URL", "http://127.0.0.1:8000/mcp")
 STATE_DIR = os.path.expanduser("~/.forget/hooks/state")
 CAPSULE_CHAR_BUDGET = 1_600  # ~400 tokens
 HANDOFF_MAX_AGE_SECONDS = 48 * 3600  # a stale shift-note is worse than none
+# The server capability these hooks are built against. The capsule response
+# carries server_version from 0.3.9 on; older servers silently drop arguments
+# these hooks send (project layering) — that mismatch must never be silent.
+REQUIRED_SERVER_VERSION = "0.3.9"
+
+
+def _version_tuple(value: str) -> tuple:
+    parts = []
+    for chunk in str(value or "").split("."):
+        digits = "".join(ch for ch in chunk if ch.isdigit())
+        parts.append(int(digits) if digits else 0)
+    return tuple(parts or [0])
+
+
+def _version_notice(server_version: str) -> str:
+    """One warning line for the capsule header area, or ''.
+
+    Two signals, no network: the server's self-reported version (mismatch =
+    features silently lost), and the update-check cache that doctor/status
+    maintain (a local file — hooks never call out).
+    """
+    if not server_version:
+        return "⚠ 서버가 버전을 안 밝힘(≤0.3.8) — 훅 기능 일부가 조용히 무시될 수 있음. 처방: forget-server upgrade"
+    if _version_tuple(server_version) < _version_tuple(REQUIRED_SERVER_VERSION):
+        return (
+            f"⚠ 서버 {server_version} < 훅 요구 {REQUIRED_SERVER_VERSION} — "
+            "프로젝트 층 등이 조용히 무시됨. 처방: forget-server upgrade"
+        )
+    try:
+        with open(os.path.expanduser("~/.forget/update-check.json"), encoding="utf-8") as fh:
+            latest = str(json.load(fh).get("latest") or "")
+        if latest and _version_tuple(server_version) < _version_tuple(latest):
+            return f"새 버전 {latest} 나옴 (현재 {server_version}) — forget-server upgrade"
+    except Exception:
+        pass
+    return ""
 
 
 def _consume_handoff() -> str:
@@ -58,17 +98,26 @@ def main() -> None:
     hook_input = json.load(sys.stdin)
     cwd = str(hook_input.get("cwd") or os.getcwd())
     source = str(hook_input.get("source") or "startup")
+    project = None if scope_disabled() else project_key_for_path(cwd)
+    arguments: dict = {
+        "query": f"session {source} in {cwd} — active tasks, open loops, recent decisions",
+        "include_debug": False,
+    }
+    # F2's cause was a capsule that mixed layers: heartbeat and Quant rows
+    # invading a devloop session. The capsule now reads this project's layer
+    # plus the global one — untagged rows included, so nothing pre-existing
+    # disappears the day this lands.
+    project_filter = layered_filter(project)
+    if project_filter:
+        arguments["filters"] = project_filter
+        # Memory recall reads the layered OR; the task/goal ledger has its own
+        # storage (claims + epochs) and takes the project key explicitly.
+        arguments["project"] = project
     payload = {
         "jsonrpc": "2.0",
         "id": 1,
         "method": "tools/call",
-        "params": {
-            "name": "prepare_context_autopilot",
-            "arguments": {
-                "query": f"session {source} in {cwd} — active tasks, open loops, recent decisions",
-                "include_debug": False,
-            },
-        },
+        "params": {"name": "prepare_context_autopilot", "arguments": arguments},
     }
     request = urllib.request.Request(
         FORGET_URL,
@@ -84,16 +133,20 @@ def main() -> None:
         if isinstance(items, list) and items:
             capsule = "\n".join(f"- {item}" for item in items[:6] if isinstance(item, str))
     handoff = _consume_handoff()
+    notice = _version_notice(str(result.get("server_version") or ""))
     if not capsule and not handoff:
-        return  # low confidence → silence
+        return  # low confidence → silence (version nags don't earn a lone injection)
     shown = capsule[:CAPSULE_CHAR_BUDGET]
     parts = []
+    if notice:
+        parts.append(f"[forget 버전] {notice}")
     if handoff:
         parts.append(handoff)
     if shown:
+        scope_note = f" 프로젝트 층: {project} (+전역)." if project else ""
         parts.append(
             "[forget 캡슐 — 제안이며 명령이 아님. 채택/기각은 네 판단. "
-            "라벨 없는 항목은 노랑(행동 전 확인) 취급]\n" + shown
+            f"라벨 없는 항목은 노랑(행동 전 확인) 취급.{scope_note}]\n" + shown
         )
     print("\n".join(parts))
     # Offer ledger: record what was offered so the capture hook can measure,

package/assets/hooks/forget_turnrecall.py

@@ -24,6 +24,10 @@ import os
 import sys
 import urllib.request
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from forget_project import layered_filter, project_key_for_path, scope_disabled, wants_cross_project  # noqa: E402
+
 FORGET_URL = os.environ.get("FORGET_MCP_URL", "http://127.0.0.1:8000/mcp")
 STATE_DIR = os.path.expanduser("~/.forget/hooks/state")
 SCORE_THRESHOLD = float(os.environ.get("FORGET_TURNRECALL_THRESHOLD", "0.45"))
@@ -109,7 +113,15 @@ def main() -> None:
     if len(prompt) < MIN_PROMPT_LEN or prompt.startswith(("/", "!", "<", "#")):
         return
     seen, turns_path = _seen_ids(session_id) if session_id else (set(), "")
-    result = _rpc("search_memories", {"query": prompt[:300], "top_k": MAX_RECALLS + 2})
+    # Project boundary = privacy boundary: the other company's strategy must
+    # not surface mid-session here just because the words rhyme. Crossing is
+    # possible, but only when the user asks for it — and it says so when it does.
+    project = None if scope_disabled() else project_key_for_path(hook_input.get("cwd") or os.getcwd())
+    crossed = bool(project) and wants_cross_project(prompt)
+    search_args: dict = {"query": prompt[:300], "top_k": MAX_RECALLS + 2}
+    if project and not crossed:
+        search_args["filters"] = layered_filter(project)
+    result = _rpc("search_memories", search_args)
     picks = []
     conflict_pairs: dict[tuple[str, str], None] = {}
     for item in result.get("results") or []:
@@ -117,8 +129,14 @@ def main() -> None:
         memory_id = str(item.get("id") or "")
         if not memory_id or memory_id in seen:
             continue
-        if (item.get("metadata") or {}).get("hook"):
+        metadata = item.get("metadata") or {}
+        if metadata.get("hook"):
             continue  # session-capture pointers are for rehydration, not recall
+        if metadata.get("assertion_kind") == "task_state":
+            # Fluid-layer task ledger rows travel via get_task_state/capsule
+            # only; surfacing them as turn recalls is friction F2's C2 cause
+            # (long claim texts farm phrase_bonus regardless of topic).
+            continue
         pair = _conflict_pair(item)
         if pair:
             if score >= CONFLICT_THRESHOLD:
@@ -152,7 +170,9 @@ def main() -> None:
             lines.append(f"- (현재) {new_text}")
             lines.append(f"- (red/구본) {old_text}")
     if picks:
-        lines.append("[forget 회상 — 이 턴과 관련된 기억 제안. green=행동 근거 OK, yellow=행동 전 확인, red=참고만]")
+        header = "[forget 회상 — 이 턴과 관련된 기억 제안. green=행동 근거 OK, yellow=행동 전 확인, red=참고만"
+        header += " / 프로젝트 경계를 넘어 검색함]" if crossed else "]"
+        lines.append(header)
         lines += [f"- ({light}) {memory}" for _, light, memory in picks]
     print("\n".join(lines))
     if session_id and turns_path:

package/bin/forget-connect.js

@@ -2,6 +2,13 @@
 
 import { main } from "../src/cli.js";
 
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on("error", (error) => {
+    if (error?.code === "EPIPE") process.exit(0);
+    throw error;
+  });
+}
+
 main().catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
   console.error(`forget-connect: ${message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forget-connect",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Safely connect Claude Code, Codex, and Claude Desktop to Forget memory.",
   "type": "module",
   "bin": {
@@ -35,4 +35,4 @@
     "directory": "packages/forget-connect"
   },
   "homepage": "https://multi-turn.ai"
-}
+}

package/src/cli.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import os from "node:os";
 import readline from "node:readline/promises";
 import { stdin, stdout, stderr } from "node:process";
 import {
@@ -7,13 +8,15 @@ import {
   ConfigError,
   applyPlan,
   buildPlan,
+  configuredServerUrl,
   detectClients,
-  detectInstalledScope,
   getClients,
   inspectClients,
   normalizeUrl,
   redactUrlForDisplay,
+  scopeFromUrl,
   scopedMcpUrl,
+  CANONICAL_APP_ID,
   validateScopeId,
   validateApiKey,
 } from "./core.js";
@@ -41,10 +44,17 @@ Usage:
 
 Options:
   --client <ids>       Comma-separated: claude-code,codex,claude-desktop,all
-  --url <url>          MCP URL (default: ${DEFAULT_MCP_URL})
+  --url <url>          Exact MCP URL to install (default base: ${DEFAULT_MCP_URL})
   --hosted             Use the managed Forget service (legacy) instead of a local server
   --user-id <id>       Memory user scope (pair with --app-id)
   --app-id <id>        Project/app scope (pair with --user-id)
+  --no-scope           Install the shared unscoped /mcp endpoint (legacy behavior)
+
+Scope:
+  Local connections default to one canonical scoped endpoint (all clients share it):
+  /mcp/<client>/http/<os-username>. This keeps each user's and client's
+  memories isolated. Override with --user-id/--app-id, or opt out with
+  --no-scope. An explicit --url is installed verbatim.
   --no-auth            Connect without a Bearer token
   --no-rules           Do not manage CLAUDE.md or AGENTS.md instruction blocks
   --no-hooks           Do not install Claude Code memory hooks (session capsule,
@@ -106,6 +116,11 @@ export function parseArgs(argv, env = process.env) {
     hostedFlag: false,
     userId: env.FORGET_USER_ID?.trim() || "",
     appId: env.FORGET_APP_ID?.trim() || "",
+    noScope: false,
+    baseUrl: "",
+    hosted: false,
+    scope: null,
+    defaultScope: null,
     auth: true,
     rules: true,
     hooks: true,
@@ -148,6 +163,8 @@ export function parseArgs(argv, env = process.env) {
       index += 1;
     } else if (arg.startsWith("--app-id=")) {
       options.appId = arg.slice("--app-id=".length);
+    } else if (arg === "--no-scope") {
+      options.noScope = true;
     } else if (arg === "--no-auth") {
       options.auth = false;
     } else if (arg === "--no-rules") {
@@ -194,6 +211,9 @@ export function parseArgs(argv, env = process.env) {
   if (Boolean(options.userId) !== Boolean(options.appId)) {
     throw new ConfigError("--user-id and --app-id must be provided together.");
   }
+  if (options.noScope && options.userId) {
+    throw new ConfigError("--no-scope and --user-id/--app-id are mutually exclusive.");
+  }
   options.scope = options.userId
     ? {
       userId: validateScopeId(options.userId, "user_id"),
@@ -203,9 +223,52 @@ export function parseArgs(argv, env = process.env) {
   options.url = options.scope
     ? scopedMcpUrl(options.baseUrl, options.scope)
     : options.baseUrl;
+  // Cold-install default: scope each client into its own memory pool at
+  // /mcp/<client>/http/<os-username>. The unscoped /mcp endpoint pools every
+  // client's memories into the server's fallback scope (cold-install audit
+  // 2026-07-29), so plain /mcp is now the opt-in (--no-scope), not the
+  // default. An explicit --url stays verbatim, and hosted keeps requiring an
+  // explicit account identity — the OS username is not a hosted account.
+  options.defaultScope = null;
+  if (!options.scope && !options.noScope && !options.hosted && !options.urlExplicit) {
+    const osUser = defaultScopeUserId(env);
+    if (osUser) options.defaultScope = { userId: osUser };
+  }
   return options;
 }
 
+function defaultScopeUserId(env) {
+  let candidate = "";
+  try {
+    candidate = os.userInfo().username?.trim() || "";
+  } catch {
+    candidate = "";
+  }
+  candidate = candidate || env.USER?.trim() || env.USERNAME?.trim() || "";
+  if (!candidate) return "";
+  try {
+    return validateScopeId(candidate, "user_id");
+  } catch {
+    // An exotic username must degrade to the unscoped legacy behavior, not
+    // block the connect.
+    return "";
+  }
+}
+
+export function urlForClient(options, client) {
+  if (options.scope) return options.url;
+  if (options.defaultScope && client) {
+    // Every client shares the canonical pool; which tool wrote a memory is
+    // provenance, not a scope boundary (issue #27). A per-client pool made
+    // Codex writes invisible to Claude and vice versa.
+    return scopedMcpUrl(options.baseUrl, {
+      userId: options.defaultScope.userId,
+      appId: CANONICAL_APP_ID,
+    });
+  }
+  return options.url;
+}
+
 function requestedClientIds(values) {
   const ids = values
     .flatMap((value) => value.split(","))
@@ -440,36 +503,54 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
     return;
   }
 
+  const urlOverrides = new Map();
+  const urlFor = (client) => urlOverrides.get(client.id) ?? urlForClient(options, client);
+
   if (options.action === "doctor" && !options.scope && !options.urlExplicit && !options.hostedFlag) {
-    // A user who connected with --user-id/--app-id will run a bare
-    // `forget-connect doctor` next; comparing their scoped install against the
-    // unscoped default URL would report false failures. Adopt the scope the
-    // installed config already carries.
-    const installed = await detectInstalledScope(clients);
-    if (installed) {
-      options.scope = { userId: installed.userId, appId: installed.appId };
-      options.baseUrl = installed.baseUrl;
+    // A user who connected with an explicit or per-client default scope will
+    // run a bare `forget-connect doctor` next; comparing their scoped install
+    // against a freshly computed URL would report false failures. Adopt the
+    // scope each installed config already carries.
+    let first = null;
+    for (const client of clients) {
+      let raw = "";
+      try {
+        raw = await readFile(client.configPath, "utf8");
+      } catch {
+        raw = "";
+      }
+      const installed = scopeFromUrl(configuredServerUrl(client, raw));
+      if (!installed) continue;
+      urlOverrides.set(client.id, scopedMcpUrl(installed.baseUrl, installed));
+      if (!first) first = installed;
+    }
+    if (first) {
+      options.scope = { userId: first.userId, appId: first.appId };
+      options.baseUrl = first.baseUrl;
       options.hosted = isHostedBaseUrl(options.baseUrl);
       options.url = scopedMcpUrl(options.baseUrl, options.scope);
-      stdout.write(
-        `Scope detected from installed config: user ${installed.userId} · app ${installed.appId}\n`,
+      const scopeNoticeStream = options.json ? stderr : stdout;
+      scopeNoticeStream.write(
+        `Scope detected from installed config: user ${first.userId} · app ${first.appId}\n`,
       );
     }
   }
 
   const apiKey = await apiKeyFor(options, env);
   if (options.action === "doctor") {
+    const probeUrl = clients.length ? urlFor(clients[0]) : options.url;
+    const probeScope = options.scope ?? scopeFromUrl(probeUrl);
     const local = localDoctorResults(
-      await inspectClients(clients, { url: options.url, apiKey }),
+      await inspectClients(clients, { url: options.url, apiKey, urlFor }),
       { requireRules: options.rules },
     );
     const remote = local.every((client) => client.ok)
       ? await doctorRemote({
-        url: options.url,
+        url: probeUrl,
         apiKey,
         timeoutMs: options.timeoutMs,
         clientVersion: await version(),
-        expectedScope: options.scope,
+        expectedScope: probeScope,
         requireScope: options.hosted,
       })
       : {
@@ -484,7 +565,7 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
         required_tools: [],
         missing_tools: [],
         scope_probe: {
-          requested: Boolean(options.scope),
+          requested: Boolean(probeScope),
           required: options.hosted,
           ok: false,
           skipped: true,
@@ -495,8 +576,8 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
       : null;
     const result = {
       ok: local.every((client) => client.ok) && remote.ok && (hooksStatus?.ok ?? true),
-      url: redactUrlForDisplay(options.url),
-      scope: { configured: Boolean(options.scope) },
+      url: redactUrlForDisplay(probeUrl),
+      scope: { configured: Boolean(probeScope) },
       clients: local,
       hooks: hooksStatus,
       remote,
@@ -508,6 +589,7 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
   }
   const changes = await buildPlan(options.action, clients, {
     url: options.url,
+    urlFor,
     apiKey,
     installInstructionRules: options.rules,
     migrateLegacy: options.migrateLegacy,
@@ -536,7 +618,7 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
       if (!error || error.code !== "ENOENT") throw error;
     }
     const settingsNext = options.action === "connect"
-      ? connectHooksSettings(settingsRaw, { hooksDir, url: options.url })
+      ? connectHooksSettings(settingsRaw, { hooksDir, url: urlFor(claudeCode) })
       : disconnectHooksSettings(settingsRaw);
     if (settingsRaw !== settingsNext) {
       changes.push({
@@ -586,6 +668,13 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
     for (const filePath of hookScriptPaths) stdout.write(`  ${hookVerb} ${filePath}\n`);
   }
   if (options.action === "connect") {
+    if (options.scope) {
+      stdout.write(`  scope: user ${options.scope.userId} · app ${options.scope.appId}\n`);
+    } else if (options.defaultScope) {
+      stdout.write(
+        `  scope: user ${options.defaultScope.userId} · app forget — one canonical pool for all clients (--no-scope opts out)\n`,
+      );
+    }
     if (manageHooks) {
       stdout.write("  hooks: session capsule, per-turn recall, conflict alerts, session capture (needs python3 on PATH)\n");
     }

package/src/core.js

@@ -15,6 +15,12 @@ import os from "node:os";
 import path from "node:path";
 
 export const DEFAULT_MCP_URL = "http://localhost:8000/mcp";
+// One canonical memory pool per user. Naming the pool after the client
+// (codex, claude-code, …) invents an empty per-tool scope and re-creates the
+// fragmentation the scoped default exists to prevent: memories written from
+// one tool become invisible to every other (issue #27, field report round 3).
+// The client's identity is provenance, not an isolation boundary.
+export const CANONICAL_APP_ID = "forget";
 export const HOSTED_MCP_URL = "https://api.multi-turn.ai/mcp";
 export const SERVER_KEY = "forget";
 export const BACKUP_SUFFIX = ".forget-backup";
@@ -582,10 +588,11 @@ function rulesCurrent(raw) {
   }
 }
 
-export async function inspectClients(clients, { url = "", apiKey = "" } = {}) {
-  const expectedUrl = url ? normalizeUrl(url) : "";
+export async function inspectClients(clients, { url = "", apiKey = "", urlFor = null } = {}) {
   return Promise.all(
     clients.map(async (client) => {
+      const clientUrl = urlFor ? urlFor(client) : url;
+      const expectedUrl = clientUrl ? normalizeUrl(clientUrl) : "";
       const configRaw = await readOptional(client.configPath);
       const rulesRaw = client.rulesPath ? await readOptional(client.rulesPath) : "";
       const expected = expectedUrl
@@ -616,6 +623,7 @@ export async function buildPlan(
     installInstructionRules = true,
     migrateLegacy = true,
     legacyUrls = [url],
+    urlFor = null,
   } = {},
 ) {
   if (!['connect', 'disconnect'].includes(action)) {
@@ -623,17 +631,20 @@ export async function buildPlan(
   }
   const changes = [];
   for (const client of clients) {
+    // urlFor lets connect scope each client into its own memory pool
+    // (/mcp/{app}/http/{user}) while everything else shares one plan.
+    const clientUrl = urlFor ? urlFor(client) : url;
     const configRaw = await readOptional(client.configPath);
     let configNext;
     if (client.kind === "toml") {
       configNext = action === "connect"
-        ? connectToml(configRaw, { url, apiKey, migrateLegacy, legacyUrls })
+        ? connectToml(configRaw, { url: clientUrl, apiKey, migrateLegacy, legacyUrls })
         : disconnectToml(configRaw);
     } else {
       configNext = action === "connect"
         ? connectJson(configRaw, {
           clientId: client.id,
-          url,
+          url: clientUrl,
           apiKey,
           migrateLegacy,
           legacyUrls,

package/src/hooks.js

@@ -20,6 +20,8 @@ export const HOOK_SCRIPTS = [
   "forget_sessionstart.py",
   "forget_turnrecall.py",
   "forget_capture.py",
+  "forget_project.py", // shared project-boundary detection (imported by the others)
+  "forget_projecttag.py", // PreToolUse: stamps memory/task writes with the cwd's project
 ];
 
 // Ownership marker: every command we install invokes a script whose path
@@ -75,6 +77,12 @@ export function hookEntries({ hooksDir, url }) {
       timeout: 10,
       statusMessage: "forget: capturing session + outcome",
     },
+    PreToolUse: {
+      command: hookCommand("forget_projecttag.py", { hooksDir, url }),
+      timeout: 5,
+      statusMessage: "forget: tagging project scope",
+      matcher: "mcp__forget__add_memory|mcp__forget__record_task_state",
+    },
   };
 }
 
@@ -124,14 +132,16 @@ export function connectHooksSettings(raw, { hooksDir, url }) {
   const hooks = validatedHooks(config, "settings.json");
   for (const [event, entry] of Object.entries(hookEntries({ hooksDir, url }))) {
     const groups = withoutOurHooks(hooks[event] ?? []);
-    groups.push({
+    const group = {
       hooks: [{
         type: "command",
         command: entry.command,
         timeout: entry.timeout,
         statusMessage: entry.statusMessage,
       }],
-    });
+    };
+    if (entry.matcher) group.matcher = entry.matcher;
+    groups.push(group);
     hooks[event] = groups;
   }
   config.hooks = hooks;