graph-mind-memory 0.5.2__tar.gz → 0.5.3__tar.gz

{graph_mind_memory-0.5.2 → graph_mind_memory-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graph-mind-memory
-Version: 0.5.2
+Version: 0.5.3
 Summary: Local-first memory for AI coding assistants: verbatim, on your own PC, no LLM calls at write time.
 Author-email: Yohan Ko <goyohan0611@gmail.com>
 License-Expression: AGPL-3.0-only
@@ -78,8 +78,8 @@ calls Graph-MIND over MCP and gets back a few thousand tokens of the conversatio
 ## Benchmarks
 
 All numbers below come from files in this repository: the pre-registrations, each question's
-answer, and the judge's verdict on it, under [`runs/`](runs). The method is in
-[REPORT.md](REPORT.md), including the failures and the corrections.
+answer, and the judge's verdict on it, under [`research/runs/`](research/runs). The method is in
+[REPORT.md](research/REPORT.md), including the failures and the corrections.
 
 **LongMemEval_S: answer accuracy, 500 questions.** The answer model is gpt-5-mini; the judge is the
 official gpt-4o-2024-08-06.
@@ -139,7 +139,7 @@ or from source:
 ```bash
 git clone https://github.com/goyohan0611-png/graph-mind.git
 cd graph-mind
-python install.py
+python src/install.py
 ```
 
 The installer:
@@ -233,7 +233,7 @@ On the PC that holds the memory, tell its AI:
 It replies with a connection code (`gm1.…`). On each other PC:
 
 ```bash
-graph-mind-install --join gm1.…     # or: python install.py --join gm1.…
+graph-mind-install --join gm1.…     # or: python src/install.py --join gm1.…
 ```
 
 The memory then lives in a Postgres server on the first PC, which Graph-MIND sets up itself. Other
@@ -254,16 +254,17 @@ each PC.
 ## Reproducing the benchmarks
 
 1. Download `longmemeval_s_cleaned.json` from [LongMemEval](https://github.com/xiaowu0162/LongMemEval)
-   into `external/longmemeval/`.
+   into `research/external/longmemeval/`.
 2. Set `OPENAI_API_KEY` for the answer model and the judge.
-3. Run the commands in [REPORT.md §10](REPORT.md#10-reproducing).
+3. `pip install -e .`, then from `research/` run the commands in
+   [REPORT.md §10](research/REPORT.md#10-reproducing).
 
 A full 500-question run costs about US$3.
 
 ## Tests
 
 ```bash
-python -m unittest discover -p "test_*.py"
+python -m unittest discover -s tests -p "test_*.py"
 ```
 
 ---
@@ -279,20 +280,17 @@ python -m unittest discover -p "test_*.py"
   can stop capture until Graph-MIND is updated.
 - **Multi-session questions are the weakest type at 80%.** These are questions that count or
   combine facts across many conversations.
-- **The repository still holds the research-phase experiments** next to the product (see
-  [Repository layout](#repository-layout)); the installed package carries only the 22 product
-  modules.
 
-The full list is in [REPORT.md §9](REPORT.md#9-known-limits).
+The full list is in [REPORT.md §9](research/REPORT.md#9-known-limits).
 
 ## Repository layout
 
-| | files |
+| folder | what is in it |
 |---|---|
-| **Product** (what `pip install graph-mind-memory` installs) | `graph_mind_mcp_server.py` (MCP server), `automatic_capture*.py` (capture service), `install.py`, `brain_log.py` (sharing across PCs), `forget.py` (deleting), `local_brain.py` / `conversation_memory.py` / `coding_memory.py` / `development_memory.py` (stores), `semantic_recall.py` / `local_embedder.py` / `vector_cache.py` / `embedding_warmup.py` (search), and their helpers |
-| **Benchmarks** | `product_answer_eval.py`, `official_judge_v073.py`, `rival_mem0.py`, `rival_mempalace.py`, `rival_clean_prereg.py`, and the result files under `runs/` |
-| **Research phase** | the other modules: earlier extraction pipelines and analyses that REPORT.md cites |
-| **Tests** | `test_*.py` |
+| [`src/`](src) | the product, exactly what `pip install graph-mind-memory` installs: `graph_mind_mcp_server.py` (MCP server), `automatic_capture*.py` (capture service), `install.py`, `brain_log.py` (sharing across PCs), `forget.py` (deleting), the stores, and search (`semantic_recall.py`, `local_embedder.py`) |
+| [`tests/`](tests) | unit tests, run in CI on Windows, Linux and macOS |
+| [`research/`](research) | the benchmark and research-phase scripts, [REPORT.md](research/REPORT.md), and every run's results under `runs/` |
+| [`demo/`](demo) | the README's GIF and the script that records it |
 
 ## Security
 

{graph_mind_memory-0.5.2 → graph_mind_memory-0.5.3}/README.md

@@ -50,8 +50,8 @@ calls Graph-MIND over MCP and gets back a few thousand tokens of the conversatio
 ## Benchmarks
 
 All numbers below come from files in this repository: the pre-registrations, each question's
-answer, and the judge's verdict on it, under [`runs/`](runs). The method is in
-[REPORT.md](REPORT.md), including the failures and the corrections.
+answer, and the judge's verdict on it, under [`research/runs/`](research/runs). The method is in
+[REPORT.md](research/REPORT.md), including the failures and the corrections.
 
 **LongMemEval_S: answer accuracy, 500 questions.** The answer model is gpt-5-mini; the judge is the
 official gpt-4o-2024-08-06.
@@ -111,7 +111,7 @@ or from source:
 ```bash
 git clone https://github.com/goyohan0611-png/graph-mind.git
 cd graph-mind
-python install.py
+python src/install.py
 ```
 
 The installer:
@@ -205,7 +205,7 @@ On the PC that holds the memory, tell its AI:
 It replies with a connection code (`gm1.…`). On each other PC:
 
 ```bash
-graph-mind-install --join gm1.…     # or: python install.py --join gm1.…
+graph-mind-install --join gm1.…     # or: python src/install.py --join gm1.…
 ```
 
 The memory then lives in a Postgres server on the first PC, which Graph-MIND sets up itself. Other
@@ -226,16 +226,17 @@ each PC.
 ## Reproducing the benchmarks
 
 1. Download `longmemeval_s_cleaned.json` from [LongMemEval](https://github.com/xiaowu0162/LongMemEval)
-   into `external/longmemeval/`.
+   into `research/external/longmemeval/`.
 2. Set `OPENAI_API_KEY` for the answer model and the judge.
-3. Run the commands in [REPORT.md §10](REPORT.md#10-reproducing).
+3. `pip install -e .`, then from `research/` run the commands in
+   [REPORT.md §10](research/REPORT.md#10-reproducing).
 
 A full 500-question run costs about US$3.
 
 ## Tests
 
 ```bash
-python -m unittest discover -p "test_*.py"
+python -m unittest discover -s tests -p "test_*.py"
 ```
 
 ---
@@ -251,20 +252,17 @@ python -m unittest discover -p "test_*.py"
   can stop capture until Graph-MIND is updated.
 - **Multi-session questions are the weakest type at 80%.** These are questions that count or
   combine facts across many conversations.
-- **The repository still holds the research-phase experiments** next to the product (see
-  [Repository layout](#repository-layout)); the installed package carries only the 22 product
-  modules.
 
-The full list is in [REPORT.md §9](REPORT.md#9-known-limits).
+The full list is in [REPORT.md §9](research/REPORT.md#9-known-limits).
 
 ## Repository layout
 
-| | files |
+| folder | what is in it |
 |---|---|
-| **Product** (what `pip install graph-mind-memory` installs) | `graph_mind_mcp_server.py` (MCP server), `automatic_capture*.py` (capture service), `install.py`, `brain_log.py` (sharing across PCs), `forget.py` (deleting), `local_brain.py` / `conversation_memory.py` / `coding_memory.py` / `development_memory.py` (stores), `semantic_recall.py` / `local_embedder.py` / `vector_cache.py` / `embedding_warmup.py` (search), and their helpers |
-| **Benchmarks** | `product_answer_eval.py`, `official_judge_v073.py`, `rival_mem0.py`, `rival_mempalace.py`, `rival_clean_prereg.py`, and the result files under `runs/` |
-| **Research phase** | the other modules: earlier extraction pipelines and analyses that REPORT.md cites |
-| **Tests** | `test_*.py` |
+| [`src/`](src) | the product, exactly what `pip install graph-mind-memory` installs: `graph_mind_mcp_server.py` (MCP server), `automatic_capture*.py` (capture service), `install.py`, `brain_log.py` (sharing across PCs), `forget.py` (deleting), the stores, and search (`semantic_recall.py`, `local_embedder.py`) |
+| [`tests/`](tests) | unit tests, run in CI on Windows, Linux and macOS |
+| [`research/`](research) | the benchmark and research-phase scripts, [REPORT.md](research/REPORT.md), and every run's results under `runs/` |
+| [`demo/`](demo) | the README's GIF and the script that records it |
 
 ## Security
 

{graph_mind_memory-0.5.2 → graph_mind_memory-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graph-mind-memory"
-version = "0.5.2"
+version = "0.5.3"
 description = "Local-first memory for AI coding assistants: verbatim, on your own PC, no LLM calls at write time."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -45,7 +45,8 @@ graph-mind-capture = "automatic_capture_cli:main"
 graph-mind-forget = "forget:main"
 
 [tool.setuptools]
-# ponytail: flat modules, as in the repository; a graph_mind/ package is the upgrade path.
+# ponytail: flat modules under src/; a graph_mind/ package is the upgrade path.
+package-dir = { "" = "src" }
 py-modules = [
     "associative_memory",
     "automatic_capture",

{graph_mind_memory-0.5.2 → graph_mind_memory-0.5.3/src}/graph_mind_mcp_server.py

@@ -26,12 +26,13 @@ if hasattr(sys.stderr, "reconfigure"):
 
 
 def _version() -> str:
-    """The package version: pyproject.toml beside this file in a source checkout, else the
+    """The package version: the checkout's pyproject.toml (one folder up from src/), else the
     installed distribution's. A hand-kept constant here had drifted to 0.5.0 at release 0.3.1."""
     import re
-    project = Path(__file__).with_name("pyproject.toml")
-    if project.exists():
-        found = re.search(r'^version = "([^"]+)"', project.read_text(encoding="utf-8"), re.M)
+    project = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    text = project.read_text(encoding="utf-8") if project.exists() else ""
+    if 'name = "graph-mind-memory"' in text:
+        found = re.search(r'^version = "([^"]+)"', text, re.M)
         if found:
             return found.group(1)
     try:
@@ -358,6 +359,21 @@ def capture_warnings() -> list[str]:
         return []
 
 
+PROACTIVE_NOTE = (
+    "Remember proactively. Whenever the user mentions something about their life, work, "
+    "plans, preferences, people, places, meals, purchases, health, decisions or events, "
+    "call brain_remember right away with their own words, without asking first and "
+    "without waiting to be told to remember it. Saving too much costs nothing; forgetting "
+    "is what the user notices. Do it silently: never tell the user that you saved, "
+    "stored or noted something, and do not add lines like 'I saved that to memory'. "
+    "Mention memory only when the user asks what you remember or whether it was saved. ")
+# set by the installer for apps whose transcripts the capture service already saves
+CAPTURED_NOTE = (
+    "Every turn of this conversation is saved automatically. Do not call brain_remember for "
+    "ordinary chat; call it only when the user explicitly asks you to remember something or "
+    "to record a decision. ")
+
+
 def build_server(db_path=None):
     database = Path(db_path).expanduser() if db_path is not None else configured_db_path()
     server = MCPServer(
@@ -365,13 +381,7 @@ def build_server(db_path=None):
         title="Graph-MIND Universal Personal Memory",
         description="User-owned local brain shared across models, sessions and applications.",
         instructions=(
-            "Remember proactively. Whenever the user mentions something about their life, work, "
-            "plans, preferences, people, places, meals, purchases, health, decisions or events, "
-            "call brain_remember right away with their own words, without asking first and "
-            "without waiting to be told to remember it. Saving too much costs nothing; forgetting "
-            "is what the user notices. Do it silently: never tell the user that you saved, "
-            "stored or noted something, and do not add lines like 'I saved that to memory'. "
-            "Mention memory only when the user asks what you remember or whether it was saved. "
+            (CAPTURED_NOTE if os.environ.get("GRAPH_MIND_CAPTURED") else PROACTIVE_NOTE) +
             "Call brain_context first when a request may depend on the user's prior conversations, "
             "facts, preferences, decisions, projects or work, including 'where did we leave off?'. "
             "It skips unrelated requests and returns a bounded evidence packet instead of "

{graph_mind_memory-0.5.2 → graph_mind_memory-0.5.3/src}/graph_mind_memory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graph-mind-memory
-Version: 0.5.2
+Version: 0.5.3
 Summary: Local-first memory for AI coding assistants: verbatim, on your own PC, no LLM calls at write time.
 Author-email: Yohan Ko <goyohan0611@gmail.com>
 License-Expression: AGPL-3.0-only
@@ -78,8 +78,8 @@ calls Graph-MIND over MCP and gets back a few thousand tokens of the conversatio
 ## Benchmarks
 
 All numbers below come from files in this repository: the pre-registrations, each question's
-answer, and the judge's verdict on it, under [`runs/`](runs). The method is in
-[REPORT.md](REPORT.md), including the failures and the corrections.
+answer, and the judge's verdict on it, under [`research/runs/`](research/runs). The method is in
+[REPORT.md](research/REPORT.md), including the failures and the corrections.
 
 **LongMemEval_S: answer accuracy, 500 questions.** The answer model is gpt-5-mini; the judge is the
 official gpt-4o-2024-08-06.
@@ -139,7 +139,7 @@ or from source:
 ```bash
 git clone https://github.com/goyohan0611-png/graph-mind.git
 cd graph-mind
-python install.py
+python src/install.py
 ```
 
 The installer:
@@ -233,7 +233,7 @@ On the PC that holds the memory, tell its AI:
 It replies with a connection code (`gm1.…`). On each other PC:
 
 ```bash
-graph-mind-install --join gm1.…     # or: python install.py --join gm1.…
+graph-mind-install --join gm1.…     # or: python src/install.py --join gm1.…
 ```
 
 The memory then lives in a Postgres server on the first PC, which Graph-MIND sets up itself. Other
@@ -254,16 +254,17 @@ each PC.
 ## Reproducing the benchmarks
 
 1. Download `longmemeval_s_cleaned.json` from [LongMemEval](https://github.com/xiaowu0162/LongMemEval)
-   into `external/longmemeval/`.
+   into `research/external/longmemeval/`.
 2. Set `OPENAI_API_KEY` for the answer model and the judge.
-3. Run the commands in [REPORT.md §10](REPORT.md#10-reproducing).
+3. `pip install -e .`, then from `research/` run the commands in
+   [REPORT.md §10](research/REPORT.md#10-reproducing).
 
 A full 500-question run costs about US$3.
 
 ## Tests
 
 ```bash
-python -m unittest discover -p "test_*.py"
+python -m unittest discover -s tests -p "test_*.py"
 ```
 
 ---
@@ -279,20 +280,17 @@ python -m unittest discover -p "test_*.py"
   can stop capture until Graph-MIND is updated.
 - **Multi-session questions are the weakest type at 80%.** These are questions that count or
   combine facts across many conversations.
-- **The repository still holds the research-phase experiments** next to the product (see
-  [Repository layout](#repository-layout)); the installed package carries only the 22 product
-  modules.
 
-The full list is in [REPORT.md §9](REPORT.md#9-known-limits).
+The full list is in [REPORT.md §9](research/REPORT.md#9-known-limits).
 
 ## Repository layout
 
-| | files |
+| folder | what is in it |
 |---|---|
-| **Product** (what `pip install graph-mind-memory` installs) | `graph_mind_mcp_server.py` (MCP server), `automatic_capture*.py` (capture service), `install.py`, `brain_log.py` (sharing across PCs), `forget.py` (deleting), `local_brain.py` / `conversation_memory.py` / `coding_memory.py` / `development_memory.py` (stores), `semantic_recall.py` / `local_embedder.py` / `vector_cache.py` / `embedding_warmup.py` (search), and their helpers |
-| **Benchmarks** | `product_answer_eval.py`, `official_judge_v073.py`, `rival_mem0.py`, `rival_mempalace.py`, `rival_clean_prereg.py`, and the result files under `runs/` |
-| **Research phase** | the other modules: earlier extraction pipelines and analyses that REPORT.md cites |
-| **Tests** | `test_*.py` |
+| [`src/`](src) | the product, exactly what `pip install graph-mind-memory` installs: `graph_mind_mcp_server.py` (MCP server), `automatic_capture*.py` (capture service), `install.py`, `brain_log.py` (sharing across PCs), `forget.py` (deleting), the stores, and search (`semantic_recall.py`, `local_embedder.py`) |
+| [`tests/`](tests) | unit tests, run in CI on Windows, Linux and macOS |
+| [`research/`](research) | the benchmark and research-phase scripts, [REPORT.md](research/REPORT.md), and every run's results under `runs/` |
+| [`demo/`](demo) | the README's GIF and the script that records it |
 
 ## Security
 

graph_mind_memory-0.5.3/src/graph_mind_memory.egg-info/SOURCES.txt

@@ -0,0 +1,63 @@
+LICENSE
+README.md
+pyproject.toml
+src/associative_memory.py
+src/automatic_capture.py
+src/automatic_capture_cli.py
+src/brain_log.py
+src/clock.py
+src/coding_memory.py
+src/conversation_memory.py
+src/development_memory.py
+src/development_paths.py
+src/embedding_warmup.py
+src/entity_timeline.py
+src/forget.py
+src/graph_mind_mcp_server.py
+src/install.py
+src/local_brain.py
+src/local_embedder.py
+src/semantic_llm_extractor.py
+src/semantic_memory.py
+src/semantic_recall.py
+src/temporal_resolver.py
+src/universal_personal_memory.py
+src/vector_cache.py
+src/graph_mind_memory.egg-info/PKG-INFO
+src/graph_mind_memory.egg-info/SOURCES.txt
+src/graph_mind_memory.egg-info/dependency_links.txt
+src/graph_mind_memory.egg-info/entry_points.txt
+src/graph_mind_memory.egg-info/requires.txt
+src/graph_mind_memory.egg-info/top_level.txt
+tests/test_associative_memory.py
+tests/test_automatic_capture.py
+tests/test_capture_health.py
+tests/test_coding_memory.py
+tests/test_cold_start.py
+tests/test_concurrent_use.py
+tests/test_conversation_memory.py
+tests/test_executable_memory.py
+tests/test_executable_plan_v2_diagnostic.py
+tests/test_forget.py
+tests/test_forget_conversation.py
+tests/test_graph_mind_mcp_server.py
+tests/test_ingestion_gate.py
+tests/test_ingestion_synonyms.py
+tests/test_install.py
+tests/test_llm_concept_planner.py
+tests/test_local_brain.py
+tests/test_longmemeval_adapter.py
+tests/test_longmemeval_ingestion_calibration.py
+tests/test_longmemeval_ingestion_preflight.py
+tests/test_longmemeval_ingestion_v7.py
+tests/test_memory_algebra.py
+tests/test_precondition_verifier.py
+tests/test_recent_recall.py
+tests/test_resume_retries.py
+tests/test_secret_masking.py
+tests/test_semantic_llm_extractor.py
+tests/test_semantic_memory.py
+tests/test_semantic_recall.py
+tests/test_shared_brain.py
+tests/test_temporal_state.py
+tests/test_universal_personal_memory.py

{graph_mind_memory-0.5.2 → graph_mind_memory-0.5.3/src}/install.py

@@ -23,6 +23,9 @@ HERE = Path(__file__).resolve().parent
 SERVER = HERE / "graph_mind_mcp_server.py"
 NAME = "graph-mind-memory"
 ENV = {"PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8"}
+# apps whose transcripts the capture service reads: every turn is saved without the model,
+# so the model need not spend a tool call on brain_remember for ordinary chat
+CAPTURED = {**ENV, "GRAPH_MIND_CAPTURED": "1"}
 
 
 def step(message):
@@ -31,7 +34,7 @@ def step(message):
 
 def packages():
     done = subprocess.run([sys.executable, "-m", "pip", "install", "--disable-pip-version-check",
-                           "-q", "-r", str(HERE / "requirements.txt")])
+                           "-q", "-r", str(HERE.parent / "requirements.txt")])
     if done.returncode:
         # PyTorch ships files nested deep enough to pass Windows' 260-character path limit when
         # Python lives under a long folder: pip then fails halfway with "No such file".
@@ -42,10 +45,10 @@ def packages():
                  "  or install Python or this folder under a shorter path, e.g. C:\\graph-mind")
 
 
-def _json_entry(path: Path, key: str = "mcpServers", **extra) -> None:
+def _json_entry(path: Path, key: str = "mcpServers", env=ENV, **extra) -> None:
     settings = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
     servers = settings.setdefault(key, {})
-    environment = {**servers.get(NAME, {}).get("env", {}), **ENV}   # keep the user's own settings
+    environment = {**servers.get(NAME, {}).get("env", {}), **env}   # keep the user's own settings
     servers[NAME] = {**extra, "command": sys.executable, "args": [str(SERVER)], "env": environment}
     temporary = path.with_suffix(".graph-mind.tmp")
     temporary.write_text(json.dumps(settings, ensure_ascii=False, indent=2), encoding="utf-8")
@@ -55,14 +58,17 @@ def _json_entry(path: Path, key: str = "mcpServers", **extra) -> None:
 def claude_code(home: Path) -> str:
     claude = shutil.which("claude")      # full path: an npm install is claude.CMD, which
     if claude:                           # Windows will not launch by its bare name
-        subprocess.run([claude, "mcp", "remove", "-s", "user", NAME], capture_output=True)
-        environment = [flag for key, value in ENV.items() for flag in ("-e", f"{key}={value}")]
-        # the name before -e: the CLI's -e takes every value that follows, the name included
-        subprocess.run([claude, "mcp", "add", "-s", "user", NAME, *environment, "--",
-                        sys.executable, str(SERVER)], check=True, capture_output=True)
-        return "Claude Code"
+        environment = [flag for key, value in CAPTURED.items() for flag in ("-e", f"{key}={value}")]
+        try:
+            subprocess.run([claude, "mcp", "remove", "-s", "user", NAME], capture_output=True)
+            # the name before -e: the CLI's -e takes every value that follows, the name included
+            subprocess.run([claude, "mcp", "add", "-s", "user", NAME, *environment, "--",
+                            sys.executable, str(SERVER)], check=True, capture_output=True)
+            return "Claude Code"
+        except (OSError, subprocess.CalledProcessError):
+            pass      # Windows refused to launch it (access denied, seen live): write the file
     if (home / ".claude.json").exists():
-        _json_entry(home / ".claude.json", type="stdio")
+        _json_entry(home / ".claude.json", env=CAPTURED, type="stdio")
         return "Claude Code"
     return ""
 
@@ -158,9 +164,9 @@ def codex(home: Path) -> str:
     text = config.read_text(encoding="utf-8") if config.exists() else ""
     header = f"[mcp_servers.{NAME}]"
     text = _without_codex_block(text)
-    environment = "\n".join(f"{key} = '{value}'" for key, value in ENV.items())
-    # required: otherwise Codex leaves out a server still starting when the first question comes
-    text += (f"\n{header}\nrequired = true\nstartup_timeout_sec = 60\n"
+    environment = "\n".join(f"{key} = '{value}'" for key, value in CAPTURED.items())
+    # not required: a memory server that fails to start must never keep a chat from starting
+    text += (f"\n{header}\nstartup_timeout_sec = 60\n"
              f"command = '{sys.executable}'\nargs = ['{SERVER}']\n\n"
              f"[mcp_servers.{NAME}.env]\n{environment}\n")
     config.write_text(text, encoding="utf-8")
@@ -171,7 +177,7 @@ def capture_service(start: bool) -> str:
     sys.path.insert(0, str(HERE))
     from automatic_capture import _atomic_json, default_config_path, default_service_state_dir, make_config
     if not default_config_path().exists():
-        config = make_config(workspace=str(HERE), project_id="project:graph-mind",
+        config = make_config(workspace=str(HERE.parent), project_id="project:graph-mind",
                              session_id="service:automatic-capture-v0.2",
                              sessions_root=str(Path.home() / ".codex" / "sessions"))
         # Conversations only. Watching a code folder is opt-in: this folder is Graph-MIND itself,
@@ -263,7 +269,7 @@ def main(argv=None):
         sys.path.insert(0, str(HERE))
         from brain_log import _decode
         _decode(args.join)
-    if not args.skip_packages and (HERE / "requirements.txt").exists():   # pip: already done
+    if not args.skip_packages and (HERE.parent / "requirements.txt").exists():   # pip: already done
         step("installing packages (the first time takes a few minutes)")
         packages()
     home = Path.home()

graph_mind_memory-0.5.3/tests/test_associative_memory.py

@@ -0,0 +1,120 @@
+import _isolate  # noqa: F401  (first: never touch the real ~/.graph-mind)
+from pathlib import Path
+import tempfile
+import unittest
+
+from associative_memory import AssociativeMemoryIndex
+from conversation_memory import ConversationMemoryStore
+from local_brain import LocalBrainStore
+
+
+T1 = "2026-09-16T10:00:00"
+
+
+class AssociativeMemoryTests(unittest.TestCase):
+    def test_explicit_link_resolves_when_target_arrives_later(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "brain.sqlite"
+            with AssociativeMemoryIndex(path) as index:
+                index.add_engram(engram_id="fact", source_kind="FIXTURE", source_id="f",
+                    scope="global", happened_at=T1, text="durable preference",
+                    related_engram_ids=["episode"])
+                index.add_engram(engram_id="episode", source_kind="FIXTURE", source_id="e",
+                    scope="global", happened_at=T1, text="original conversation evidence")
+                edge = index.db.execute("""SELECT relation FROM associative_edges
+                  WHERE source_engram_id='fact' AND target_engram_id='episode'""").fetchone()
+                pending = index.db.execute(
+                    "SELECT COUNT(*) FROM associative_pending_edges").fetchone()[0]
+            self.assertEqual(edge["relation"], "EXPLICIT")
+            self.assertEqual(pending, 0)
+
+    def test_spreading_activation_finds_indirect_related_memory(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "brain.sqlite"
+            with AssociativeMemoryIndex(path) as index:
+                index.add_engram(engram_id="a", source_kind="FIXTURE", source_id="a",
+                    scope="global", happened_at=T1,
+                    text="memory error in the personal brain", cues=["stale"], strength=0.8)
+                index.add_engram(engram_id="b", source_kind="FIXTURE", source_id="b",
+                    scope="global", happened_at=T1,
+                    text="stale state fixed with checkpoint", cues=["stale"], strength=0.8)
+                index.add_engram(engram_id="c", source_kind="FIXTURE", source_id="c",
+                    scope="global", happened_at=T1,
+                    text="checkpoint design documented in architecture note",
+                    cues=["checkpoint"], strength=0.8)
+                result = index.activate("personal brain memory error", hops=2, limit=3)
+            ids = [item["engram_id"] for item in result["results"]]
+            self.assertEqual(ids[0], "a")
+            self.assertIn("c", ids)
+            c = next(item for item in result["results"] if item["engram_id"] == "c")
+            self.assertEqual(len(c["activation_path"]), 2)
+
+    def test_activation_is_bounded(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "brain.sqlite"
+            with AssociativeMemoryIndex(path) as index:
+                for number in range(30):
+                    index.add_engram(engram_id=f"e{number}", source_kind="FIXTURE",
+                        source_id=str(number), scope="global", happened_at=T1,
+                        text=f"shared memory topic item {number}", cues=["shared"],
+                        max_automatic_links=8)
+                result = index.activate("shared memory", seed_limit=5, hops=4,
+                                        fanout=3, max_nodes=7, limit=5)
+            self.assertLessEqual(result["seed_count"], 5)
+            self.assertLessEqual(result["visited_nodes"], 7)
+            self.assertLessEqual(len(result["results"]), 5)
+
+    def test_external_language_adapter_can_supply_composable_concept_cues(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "brain.sqlite"
+            with AssociativeMemoryIndex(path) as index:
+                index.add_engram(engram_id="architecture", source_kind="FIXTURE",
+                    source_id="architecture", scope="global", happened_at=T1,
+                    text="bounded associative layer with deterministic executor evidence vault")
+                index.add_engram(engram_id="generic-name", source_kind="FIXTURE",
+                    source_id="generic-name", scope="global", happened_at=T1,
+                    text="document name field")
+                raw = index.activate("사람 뇌 같은 조합", limit=3)
+                planned = index.activate("사람 뇌 같은 조합",
+                    concept_cues=["associative", "deterministic executor", "evidence vault"],
+                    limit=3, minimum_concept_coverage=0.75)
+                withheld = index.activate("내 반려동물 이름이 뭐였지",
+                    concept_cues=["pet name"], limit=3,
+                    minimum_concept_coverage=0.75)
+            self.assertEqual(raw["status"], "UNKNOWN")
+            self.assertEqual(planned["results"][0]["engram_id"], "architecture")
+            self.assertEqual(len(planned["concept_cues_used"]), 3)
+            self.assertEqual(withheld["status"], "UNKNOWN")
+            self.assertEqual(withheld["reason"], "INSUFFICIENT_CONCEPT_COVERAGE")
+
+    def test_sync_preserves_sources_as_evidence_pointers(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "brain.sqlite"
+            with LocalBrainStore(path) as brain:
+                brain.remember({"memory_id": "preference", "scope": "global",
+                    "memory_type": "PREFERENCE", "title": "answer style",
+                    "content": "The user prefers concise answers.",
+                    "effective_at": T1, "known_at": T1, "actor": "user",
+                    "tags": ["style"], "entities": ["user"],
+                    "provenance": {"source_type": "fixture", "source_ref": "turn:1"},
+                    "supersedes_memory_id": None, "memory_class": "PREFERENCE",
+                    "importance": 0.9})
+            with ConversationMemoryStore(path) as conversations:
+                conversations.record({"turn_id": "turn-2", "client": "other-agent",
+                    "client_session_id": "session-1", "scope": "global", "cwd": None,
+                    "happened_at": T1, "known_at": T1, "role": "user",
+                    "content_redacted": "Please remember my concise answer style.",
+                    "raw_sha256": "abc", "redaction_count": 0,
+                    "source_path": "fixture.jsonl", "source_ordinal": 1})
+            with AssociativeMemoryIndex(path) as index:
+                synced = index.sync_sources()
+                result = index.activate("concise answer style", limit=5)
+                again = index.sync_sources()
+            self.assertEqual(synced["indexed_total"], 2)
+            self.assertEqual(again["status"], "NO_NEW_ENGRAMS")
+            self.assertEqual({item["source_kind"] for item in result["results"]},
+                             {"LOCAL_MEMORY", "CONVERSATION"})
+
+
+if __name__ == "__main__":
+    unittest.main()