groundmemory 0.3.2__tar.gz → 0.3.4__tar.gz

{groundmemory-0.3.2 → groundmemory-0.3.4}/.github/workflows/pypi-publish.yml

@@ -1,4 +1,4 @@
-name: Publish Package and Create Release
+name: Publish & Release
 
 on:
   push:

{groundmemory-0.3.2 → groundmemory-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: groundmemory
-Version: 0.3.2
+Version: 0.3.4
 Summary: Persistent, semantic memory for AI agents - mcp-native, local-first, framework-agnostic, production-ready
 Project-URL: Documentation, https://github.com/huss-mo/GroundMemory/blob/master/DOCS.md
 Project-URL: Issues, https://github.com/huss-mo/GroundMemory/issues
@@ -31,9 +31,9 @@ Description-Content-Type: text/markdown
 **Persistent, semantic memory for AI agents - mcp-native, local-first, framework-agnostic, production-ready.**
 
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
-[![Release](https://github.com/huss-mo/GroundMemory/actions/workflows/publish-release.yml/badge.svg?event=push)](https://github.com/huss-mo/GroundMemory/actions/workflows/publish-release.yml)
+[![Release](https://github.com/huss-mo/GroundMemory/actions/workflows/pypi-publish.yml/badge.svg?event=push)](https://github.com/huss-mo/GroundMemory/actions/workflows/pypi-publish.yml)
 [![Unit Tests](https://github.com/huss-mo/GroundMemory/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/huss-mo/GroundMemory/actions/workflows/unit-tests.yml)
-[![Test Suite](https://img.shields.io/badge/test%20suite-380%20tests-blue.svg)](#running-the-test-suite)
+[![Test Suite](https://img.shields.io/badge/test%20suite-386%20tests-blue.svg)](#running-the-test-suite)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![GitHub repo size](https://img.shields.io/github/repo-size/huss-mo/GroundMemory)
 ![GitHub language count](https://img.shields.io/github/languages/count/huss-mo/GroundMemory)

{groundmemory-0.3.2 → groundmemory-0.3.4}/README.md

@@ -5,9 +5,9 @@
 **Persistent, semantic memory for AI agents - mcp-native, local-first, framework-agnostic, production-ready.**
 
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
-[![Release](https://github.com/huss-mo/GroundMemory/actions/workflows/publish-release.yml/badge.svg?event=push)](https://github.com/huss-mo/GroundMemory/actions/workflows/publish-release.yml)
+[![Release](https://github.com/huss-mo/GroundMemory/actions/workflows/pypi-publish.yml/badge.svg?event=push)](https://github.com/huss-mo/GroundMemory/actions/workflows/pypi-publish.yml)
 [![Unit Tests](https://github.com/huss-mo/GroundMemory/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/huss-mo/GroundMemory/actions/workflows/unit-tests.yml)
-[![Test Suite](https://img.shields.io/badge/test%20suite-380%20tests-blue.svg)](#running-the-test-suite)
+[![Test Suite](https://img.shields.io/badge/test%20suite-386%20tests-blue.svg)](#running-the-test-suite)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![GitHub repo size](https://img.shields.io/github/repo-size/huss-mo/GroundMemory)
 ![GitHub language count](https://img.shields.io/github/languages/count/huss-mo/GroundMemory)

{groundmemory-0.3.2 → groundmemory-0.3.4}/groundmemory/bootstrap/injector.py

@@ -44,8 +44,8 @@ def _read_capped(path: Path, max_chars: int) -> tuple[str, bool]:
 def _section(title: str, body: str, truncated: bool = False, source: str = "") -> str:
     """Wrap *body* in a labelled Markdown block."""
     marker = " [TRUNCATED - use memory_get to read the rest]" if truncated else ""
-    source_line = f"*{source}*\n\n" if source else ""
-    return f"### {title}{marker} ({source_line})\n\n{body}\n"
+    source_block = f" ({source})" if source else ""
+    return f"### {title}{marker}{source_block}\n\n{body}\n"
 
 
 # ---------------------------------------------------------------------------
@@ -107,12 +107,20 @@ def build_bootstrap_prompt(
         total_chars += len(body_text)
         return total_chars < cfg.max_total_chars
 
-    # 1. Long-term memory (MEMORY.md)
-    if cfg.inject_long_term_memory:
+    # Check whether first-run onboarding is active (file exists and is non-empty).
+    # When active, skip MEMORY.md and USER.md - they are empty/default and would
+    # only confuse the model during onboarding.
+    first_run_active = (
+        workspace.first_run_file.exists()
+        and workspace.first_run_file.read_text(encoding="utf-8").strip() != ""
+    )
+
+    # 1. Long-term memory (MEMORY.md) - skipped during first run
+    if cfg.inject_long_term_memory and not first_run_active:
         _add("Long-Term Memory", workspace.memory_file)
 
-    # 2. User profile (USER.md)
-    if cfg.inject_user_profile:
+    # 2. User profile (USER.md) - skipped during first run
+    if cfg.inject_user_profile and not first_run_active:
         _add("User Profile", workspace.user_file)
 
     # 3. Agent roster (AGENTS.md)
@@ -139,6 +147,10 @@ def build_bootstrap_prompt(
             if not _add(label, day_path, source=f"daily/{day_path.name}"):
                 break  # budget exhausted
 
+    # 6. First-run onboarding (FIRST_RUN.md) - injected last; skipped automatically once emptied
+    if first_run_active:
+        _add("First Run", workspace.first_run_file)
+
     if not sections:
         return ""
 

{groundmemory-0.3.2 → groundmemory-0.3.4}/groundmemory/core/storage.py

@@ -218,8 +218,10 @@ def hard_delete_lines(path: Path, start_line: int, end_line: int) -> dict:
 
     if start_line < 1 or start_line > total:
         return {"error": f"start_line {start_line} out of range (file has {total} lines)"}
-    if end_line < start_line or end_line > total:
-        return {"error": f"end_line {end_line} out of range (start={start_line}, total={total})"}
+    if end_line < start_line:
+        return {"error": f"end_line {end_line} must be >= start_line {start_line}"}
+    # Clamp end_line silently if it exceeds the file length
+    end_line = min(end_line, total)
 
     # Convert to 0-indexed
     s = start_line - 1
@@ -277,8 +279,10 @@ def replace_lines(path: Path, start_line: int, end_line: int, replacement: str)
 
     if start_line < 1 or start_line > total:
         return {"error": f"start_line {start_line} out of range (file has {total} lines)"}
-    if end_line < start_line or end_line > total:
-        return {"error": f"end_line {end_line} out of range (start={start_line}, total={total})"}
+    if end_line < start_line:
+        return {"error": f"end_line {end_line} must be >= start_line {start_line}"}
+    # Clamp end_line silently if it exceeds the file length
+    end_line = min(end_line, total)
 
     # Convert to 0-indexed
     s = start_line - 1

{groundmemory-0.3.2 → groundmemory-0.3.4}/groundmemory/core/workspace.py

@@ -144,6 +144,39 @@ Every non-blank, non-comment line must follow this exact format:
 Lines that do not match will be rejected by the write tools.
 """
 
+_DEFAULT_FIRST_RUN_MD = """\
+# First Run
+
+If you are seeing this section, then this is the user's very first session 
+with GroundMemory. Your memory is completely empty. You are meeting them for 
+the first time - make it feel like the start of something, not a setup wizard.
+
+What to do:
+
+1. Open warmly and explain what GroundMemory means for them. Something like:
+
+   "Hey! Welcome - this is the start of something good. I have persistent memory,
+   so anything we talk about I'll carry with me into every future session. No need
+   to repeat yourself down the line."
+
+   Use your own words. Don't copy this exactly.
+
+2. In the same message, ask your questions - each on its own line, not crammed
+   together. Keep it light:
+
+   - What should you call them? (And invite them to give you a name too, if they want.)
+   - Is there anything they always want you to keep in mind?
+
+   End with something relaxed, like: "No rush - just getting to know you."
+
+3. Once they have answered, save what you learned:
+   - Name, preferences, working style -> USER.md
+   - How they want you to behave -> AGENTS.md
+   - You can also use the other memory file or tools (Ex. memory_relate) as you see fit
+
+Do not mention this file to the user. Just have the conversation.
+"""
+
 _DEFAULT_RELATIONS_MD = """\
 # Relations
 
@@ -210,6 +243,10 @@ class Workspace:
     def relations_file(self) -> Path:
         return self.path / "RELATIONS.md"
 
+    @property
+    def first_run_file(self) -> Path:
+        return self.path / "FIRST_RUN.md"
+
     def daily_file(self, day: date | None = None) -> Path:
         """Return the path for the daily log of *day* (defaults to today)."""
         d = day or date.today()
@@ -229,6 +266,7 @@ class Workspace:
         self._seed(self.user_file, _DEFAULT_USER_MD)
         self._seed(self.agents_file, _DEFAULT_AGENTS_MD)
         self._seed(self.relations_file, _DEFAULT_RELATIONS_MD)
+        self._seed(self.first_run_file, _DEFAULT_FIRST_RUN_MD)
 
     @staticmethod
     def _seed(path: Path, content: str) -> None:

{groundmemory-0.3.2 → groundmemory-0.3.4}/groundmemory/tools/base.py

@@ -44,6 +44,22 @@ _IMMUTABLE_MSG = (
 )
 
 
+def _auto_clear_first_run(session) -> None:
+    """
+    Silently empty FIRST_RUN.md after the first successful write operation.
+
+    This marks onboarding as complete without requiring the model to do it
+    explicitly.  Safe to call on every write - does nothing once the file
+    is already empty.
+    """
+    try:
+        fr = session.workspace.first_run_file
+        if fr.exists() and fr.read_text(encoding="utf-8").strip():
+            fr.write_text("", encoding="utf-8")
+    except Exception:  # noqa: BLE001
+        pass  # Never let this interfere with the actual write result
+
+
 def sync_after_edit(
     session,
     resolved: Path,
@@ -80,4 +96,5 @@ def sync_after_edit(
         base_payload["format_reminder"] = RELATIONS_FORMAT_REMINDER
         if relation_sync_result:
             base_payload["relations_synced"] = relation_sync_result
+    _auto_clear_first_run(session)
     return ok(base_payload)

{groundmemory-0.3.2 → groundmemory-0.3.4}/groundmemory/tools/memory_write.py

@@ -276,4 +276,6 @@ def run(
         sync.sync_file(daily_path, session.index, session.provider, session.config.chunking)
 
     result["mode"] = "append"
-    return ok(result)
+    from groundmemory.tools.base import _auto_clear_first_run
+    _auto_clear_first_run(session)
+    return ok(result)

{groundmemory-0.3.2 → groundmemory-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "groundmemory"
-version = "0.3.2"
+version = "0.3.4"
 description = "Persistent, semantic memory for AI agents - mcp-native, local-first, framework-agnostic, production-ready"
 readme = "README.md"
 requires-python = ">=3.12"

{groundmemory-0.3.2 → groundmemory-0.3.4}/tests/test_memory_replace.py

@@ -435,16 +435,19 @@ class TestReplaceLines:
         )
         assert r["status"] == "error"
 
-    def test_replace_lines_error_end_line_beyond_file(self, session):
+    def test_replace_lines_end_line_beyond_file_clamped(self, session):
+        """end_line beyond file length is silently clamped to the last line."""
         _write_user(session, "a\nb\n")
         r = session.execute_tool(
             "memory_write",
             file="USER.md",
             start_line=1,
             end_line=5,
-            content="x",
+            content="CLAMPED",
         )
-        assert r["status"] == "error"
+        assert r["status"] == "ok"
+        content = _get(session, "USER.md")
+        assert "CLAMPED" in content
 
 
 class TestReplaceLinesImmutable:

{groundmemory-0.3.2 → groundmemory-0.3.4}/tests/test_memory_write.py

@@ -313,4 +313,49 @@ class TestMemoryWriteDelete:
         content = _read(session, "AGENTS.md")
         assert "Rule B." not in content
         assert "Rule A." in content
-        assert "Rule C." in content
+        assert "Rule C." in content
+
+
+# ===========================================================================
+# FIRST_RUN.md auto-clear
+# ===========================================================================
+
+
+class TestFirstRunAutoCleared:
+    """FIRST_RUN.md must be emptied automatically on the first successful write."""
+
+    def test_first_run_cleared_after_append(self, session):
+        assert session.workspace.first_run_file.read_text(encoding="utf-8").strip() != ""
+        session.execute_tool("memory_write", file="USER.md", content="Name is Alice.")
+        assert session.workspace.first_run_file.read_text(encoding="utf-8").strip() == ""
+
+    def test_first_run_cleared_after_replace_text(self, session):
+        _write_user(session, "old name\n")
+        assert session.workspace.first_run_file.read_text(encoding="utf-8").strip() != ""
+        session.execute_tool("memory_write", file="USER.md", search="old name", content="new name")
+        assert session.workspace.first_run_file.read_text(encoding="utf-8").strip() == ""
+
+    def test_first_run_cleared_after_replace_lines(self, session):
+        _write_user(session, "line one\nline two\n")
+        assert session.workspace.first_run_file.read_text(encoding="utf-8").strip() != ""
+        session.execute_tool("memory_write", file="USER.md", start_line=1, end_line=1, content="replaced")
+        assert session.workspace.first_run_file.read_text(encoding="utf-8").strip() == ""
+
+    def test_first_run_cleared_after_delete(self, session):
+        _write_user(session, "line one\nline two\n")
+        assert session.workspace.first_run_file.read_text(encoding="utf-8").strip() != ""
+        session.execute_tool("memory_write", file="USER.md", start_line=1, end_line=1, content="")
+        assert session.workspace.first_run_file.read_text(encoding="utf-8").strip() == ""
+
+    def test_first_run_already_empty_stays_empty(self, session):
+        session.workspace.first_run_file.write_text("", encoding="utf-8")
+        session.execute_tool("memory_write", file="USER.md", content="Another entry.")
+        assert session.workspace.first_run_file.read_text(encoding="utf-8").strip() == ""
+
+    def test_failed_write_does_not_clear_first_run(self, session):
+        """A failed write must not trigger the auto-clear."""
+        assert session.workspace.first_run_file.read_text(encoding="utf-8").strip() != ""
+        # This write will fail (empty content)
+        r = session.execute_tool("memory_write", file="USER.md", content="")
+        assert r["status"] == "error"
+        assert session.workspace.first_run_file.read_text(encoding="utf-8").strip() != ""

{groundmemory-0.3.2 → groundmemory-0.3.4}/tests/test_session.py

@@ -121,6 +121,8 @@ class TestSessionBootstrap:
         # An empty workspace should produce minimal/empty bootstrap
 
     def test_bootstrap_includes_long_term_memory(self, session):
+        # Simulate post-onboarding: FIRST_RUN.md must be empty so MEMORY.md is injected
+        session.workspace.first_run_file.write_text("", encoding="utf-8")
         content = "Bootstrap long term fact."
         session.execute_tool("memory_write", file="MEMORY.md", content=content)
         result = session.bootstrap()