fix(memory): legible capacity errors, list action, and full-store education

The project-memory budget check silently added a 3-char entry delimiter that
the rejection message never disclosed, so a near-full store reported e.g.
"2085/2200, entry (113) exceeds" — math that reads as satisfiable (2085+113<2200)
but isn't. With no visibility into the true ceiling or what was stored, the agent
could only blind-shrink the entry and loop until interrupted.

- project_memory: delimiter-aware accounting; rejections now report exact free
  chars, the entry's real cost (content + separator), used/limit, and a compact
  inventory (index, size, preview) so the next remove/replace is guided. Add
  status() and capacity(); flag capacity failures via MemoryOpResult.full.
- Memory tool: new read-only `list` action for mid-session introspection; on a
  full-store rejection, append a plain-language explanation (nothing lost, task
  continues, how to free space) to the user-facing tool card.
- Raise limits MEMORY 2200->5000, USER 1375->2500 (within the 8 KB injection budget).
- /memory: show per-store capacity and a "nearly full" guidance panel at >=85%.
- memory.md: best-effort housekeeping guidance — don't loop on rejection.

Author: elkaix

src/pythinker_code/project_memory.py

@@ -35,8 +35,8 @@
     from pythinker_code.soul.pythinkersoul import PythinkerSoul
 
 ENTRY_DELIMITER = "\n§\n"
-MEMORY_CHAR_LIMIT = 2200
-USER_CHAR_LIMIT = 1375
+MEMORY_CHAR_LIMIT = 5000
+USER_CHAR_LIMIT = 2500
 INJECTION_BUDGET_BYTES = 8 * 1024
 _JOURNAL_MAX_ENTRIES = 100
 
@@ -92,6 +92,9 @@ async def project_key(work_dir: HostPath, *, git_runner: GitRunner | None = None
 class MemoryOpResult:
     ok: bool
     message: str
+    # True only when the op failed because the store is at capacity. Lets the UI
+    # layer attach user-facing guidance without string-matching the message.
+    full: bool = False
 
 
 class ProjectMemoryStore:
@@ -130,6 +133,31 @@ def _filename(self, target: Target) -> str:
     def _char_limit(self, target: Target) -> int:
         return self._user_limit if target == "user" else self._memory_limit
 
+    @staticmethod
+    def _used(entries: list[str]) -> int:
+        return len(ENTRY_DELIMITER.join(entries))
+
+    @staticmethod
+    def _append_overhead(entries: list[str]) -> int:
+        """Chars an appended entry costs beyond its own text (the joining delimiter)."""
+        return len(ENTRY_DELIMITER) if entries else 0
+
+    @staticmethod
+    def _inventory(entries: list[str]) -> str:
+        """Compact, model-readable listing: index, size, and a one-line preview.
+
+        The preview doubles as a copy-paste ``old_text`` substring for remove/replace,
+        turning a space-rejection into a guided one-step fix instead of a guessing game.
+        """
+        if not entries:
+            return "  (none)"
+        lines: list[str] = []
+        for i, entry in enumerate(entries):
+            preview = " ".join(entry.split())
+            clipped = preview[:60] + ("…" if len(preview) > 60 else "")
+            lines.append(f"  [{i}] {len(entry)} chars — {clipped}")
+        return "\n".join(lines)
+
     async def _path_for(self, target: Target) -> Path:
         root = await self._ensure_dir()
         return root / "memory" / self._filename(target)
@@ -219,13 +247,19 @@ async def add(self, target: Target, content: str) -> MemoryOpResult:
             if content in entries:
                 return MemoryOpResult(True, "Entry already exists (no duplicate added).")
             limit = self._char_limit(target)
-            new_total = len(ENTRY_DELIMITER.join([*entries, content]))
-            if new_total > limit:
-                current = len(ENTRY_DELIMITER.join(entries))
+            if len(ENTRY_DELIMITER.join([*entries, content])) > limit:
+                used = self._used(entries)
+                overhead = self._append_overhead(entries)
+                free = max(0, limit - used - overhead)
+                need = len(content) + overhead
                 return MemoryOpResult(
                     False,
-                    f"Memory at {current}/{limit} chars; this entry ({len(content)}) "
-                    "exceeds the limit. Replace or remove entries first.",
+                    f"Not enough room: this entry needs {need} chars "
+                    f"(content {len(content)} + {overhead} separator), but only {free} free "
+                    f"({used}/{limit} used). Remove or replace an entry to free space, "
+                    f"or shorten this entry to ≤{free} chars.\n"
+                    f"Current entries:\n{self._inventory(entries)}",
+                    full=True,
                 )
             await self._write_entries(target, [*entries, content])
         return MemoryOpResult(True, "Entry added.")
@@ -265,8 +299,16 @@ async def replace(self, target: Target, old_text: str, new_content: str) -> Memo
             limit = self._char_limit(target)
             candidate = list(entries)
             candidate[idx] = new_content
-            if len(ENTRY_DELIMITER.join(candidate)) > limit:
-                return MemoryOpResult(False, f"Replacement would exceed the {limit}-char limit.")
+            projected = self._used(candidate)
+            if projected > limit:
+                over = projected - limit
+                return MemoryOpResult(
+                    False,
+                    f"Replacement too large by {over} chars: result would be "
+                    f"{projected}/{limit}. Shorten the new text by ≥{over} chars, or remove "
+                    f"another entry first.\nCurrent entries:\n{self._inventory(entries)}",
+                    full=True,
+                )
             await self._write_entries(target, candidate)
         return MemoryOpResult(True, "Entry replaced.")
 
@@ -289,6 +331,31 @@ async def remove(self, target: Target, old_text: str) -> MemoryOpResult:
             await self._write_entries(target, entries)
         return MemoryOpResult(True, "Entry removed.")
 
+    async def capacity(self, target: Target) -> tuple[int, int, int]:
+        """Return ``(used, limit, free)`` chars for ``target`` (free accounts for the
+        delimiter a new entry would cost). Used by the UI to show/explain capacity."""
+        entries = await self.read_entries(target)
+        limit = self._char_limit(target)
+        used = self._used(entries)
+        free = max(0, limit - used - self._append_overhead(entries))
+        return used, limit, free
+
+    async def status(self, target: Target) -> str:
+        """Read-only capacity + inventory snapshot for mid-session introspection.
+
+        Lets the agent see what is stored, at what size, and exactly how much room
+        is free before attempting a write — so it can remove/consolidate instead of
+        repeatedly retrying an over-budget add.
+        """
+        entries = await self.read_entries(target)
+        limit = self._char_limit(target)
+        used = self._used(entries)
+        free = max(0, limit - used - self._append_overhead(entries))
+        return (
+            f"{self._filename(target)}: {used}/{limit} chars across {len(entries)} "
+            f"entries; {free} free for a new entry.\nCurrent entries:\n{self._inventory(entries)}"
+        )
+
     async def append_journal(self, recap: str) -> MemoryOpResult:
         """Prepend one stable session recap to ``JOURNAL.md`` if it is new."""
         recap = recap.strip()

src/pythinker_code/tools/memory/__init__.py

@@ -10,7 +10,7 @@
 
 
 class Params(BaseModel):
-    action: Literal["add", "replace", "remove"] = Field(description="The memory operation.")
+    action: Literal["add", "replace", "remove", "list"] = Field(description="The memory operation.")
     target: Literal["memory", "user"] = Field(description="Which store to write.")
     content: str | None = Field(default=None, description="Entry text for add/replace.")
     old_text: str | None = Field(
@@ -43,6 +43,10 @@ async def __call__(self, params: Params) -> ToolReturnValue:
                 message="old_text is required for replace/remove.", brief="memory: no old_text"
             )
 
+        if params.action == "list":
+            output = await self._store.status(params.target)
+            return ToolOk(output=output, message=output, brief="list")
+
         if params.action == "add":
             result = await self._store.add(params.target, params.content or "")
         elif params.action == "replace":
@@ -53,7 +57,18 @@ async def __call__(self, params: Params) -> ToolReturnValue:
             result = await self._store.remove(params.target, params.old_text or "")
 
         if not result.ok:
-            return ToolError(message=result.message, brief="memory: rejected")
+            message = result.message
+            if result.full:
+                # Educate the human reading the tool card: what happened, that nothing
+                # was lost, and the real ways to fix it. Kept short and command-accurate.
+                message += (
+                    "\n\nProject memory for this repo is full — nothing was lost, and your "
+                    "task can continue. To free space: ask me to merge or drop stale entries, "
+                    "run /memory to see what's stored, or edit MEMORY.md / USER.md directly. "
+                    "Memory is for durable facts only, so occasional pruning is expected."
+                )
+            brief = "memory: full" if result.full else "memory: rejected"
+            return ToolError(message=message, brief=brief)
         rearm = getattr(self._runtime, "rearm_injection", None)
         if rearm is not None:
             rearm("project_memory")

src/pythinker_code/tools/memory/memory.md

@@ -18,3 +18,14 @@ ACTIONS:
 - `add`: append a new entry (requires `content`).
 - `replace`: update an entry (`old_text` = a unique substring of the target entry; `content` = new text).
 - `remove`: delete an entry (`old_text` = a unique substring of the target entry).
+- `list`: show current entries with their sizes and how much room is free (read-only).
+
+WHEN A WRITE IS REJECTED FOR SPACE:
+The error reports the exact free budget and lists existing entries. Do NOT retry the
+same write with a slightly shorter entry — instead `remove` or `replace` a stale or
+redundant entry to free room, or consolidate two entries into one. Use `list` first if
+unsure what is stored.
+
+Memory writes are best-effort housekeeping: if room cannot be freed in one or two
+steps, drop the write and continue the user's actual task. Never loop on a rejected
+memory write.

src/pythinker_code/ui/shell/slash.py

@@ -2016,7 +2016,7 @@ async def show_memory(app: Shell, args: str):
     soul = ensure_pythinker_soul(app)
     if soul is None:
         return
-    from pythinker_code.project_memory import ProjectMemoryStore
+    from pythinker_code.project_memory import ProjectMemoryStore, Target
 
     store = ProjectMemoryStore(soul.runtime.work_dir)
     parts = args.split()
@@ -2062,6 +2062,25 @@ async def show_memory(app: Shell, args: str):
         return
     console.print(block)
 
+    # Capacity line + education: surface how full each store is so the user
+    # understands the "memory full" rejection and how to act on it.
+    near_full = False
+    cap_parts: list[str] = []
+    targets: tuple[tuple[Target, str], ...] = (("memory", "Project"), ("user", "User"))
+    for target, label in targets:
+        used, limit, free = await store.capacity(target)
+        cap_parts.append(f"{label} {used}/{limit} ({free} free)")
+        if limit and used / limit >= 0.85:
+            near_full = True
+    console.print(f"\n[dim]Capacity — {' · '.join(cap_parts)}[/dim]")
+    if near_full:
+        console.print(
+            "[yellow]Memory is nearly full.[/yellow] When full, new facts are rejected "
+            "(nothing is lost). To make room: ask the agent to merge or drop stale entries, "
+            "or edit MEMORY.md / USER.md directly. Memory holds only durable facts, so "
+            "occasional pruning is expected."
+        )
+
 
 @registry.command(name="update", aliases=["upgrade"])
 async def update_command(app: Shell, args: str):

tests/core/test_project_memory.py

@@ -158,8 +158,54 @@ async def test_add_success_dedup_guard_and_limit(tmp_path, monkeypatch):
     r = await store.add("memory", "   ")
     assert not r.ok
 
+    # Over-budget add: the message must disclose the exact free space (delimiter
+    # included) and list current entries so the model can free room in one step,
+    # instead of blind-shrinking against an invisible boundary.
     r = await store.add("memory", "x" * 60)
-    assert not r.ok and "limit" in r.message.lower()
+    assert not r.ok
+    # used=11 ("uses pytest"), overhead=3 (delimiter), free = 40 - 11 - 3 = 26.
+    assert "26 free" in r.message
+    assert "11/40" in r.message
+    assert "uses pytest" in r.message  # inventory preview present
+
+
+async def test_add_rejection_accounts_for_delimiter_overhead(tmp_path, monkeypatch):
+    """An entry that fits the raw budget but not the delimiter must still be rejected,
+    and the message must state the true free budget (limit - used - delimiter)."""
+    store = _store(tmp_path, monkeypatch)  # limit 40
+    await store.add("memory", "x" * 35)  # used = 35
+    # Raw free = 5, but a new entry also costs the 3-char delimiter, so only 2
+    # content chars actually fit. A 4-char entry (35+3+4=42 > 40) must be rejected.
+    r = await store.add("memory", "abcd")
+    assert not r.ok
+    assert "2 free" in r.message
+    # And the largest entry that DOES fit (35+3+2=40) is accepted.
+    r = await store.add("memory", "ab")
+    assert r.ok
+
+
+async def test_status_reports_capacity_and_inventory(tmp_path, monkeypatch):
+    store = _store(tmp_path, monkeypatch)  # limit 40
+
+    empty = await store.status("memory")
+    assert "0/40" in empty
+    assert "(none)" in empty
+
+    await store.add("memory", "uses pytest")
+    s = await store.status("memory")
+    assert "11/40" in s
+    assert "26 free" in s  # 40 - 11 - 3
+    assert "uses pytest" in s
+
+
+async def test_replace_over_limit_reports_overage(tmp_path, monkeypatch):
+    store = _store(tmp_path, monkeypatch)  # limit 40
+    await store.add("memory", "short")  # used = 5
+
+    r = await store.replace("memory", "short", "y" * 50)
+    assert not r.ok
+    assert "by 10 chars" in r.message  # 50 - 40
+    assert "short" in r.message  # inventory present
 
 
 async def test_replace_matches_substring_and_errors(tmp_path, monkeypatch):

tests/tools/test_memory_tool.py

@@ -58,6 +58,21 @@ async def test_memory_tool_add_and_read_back(tmp_path, monkeypatch):
     assert calls == ["project_memory"]
 
 
+async def test_memory_tool_list_reports_status(tmp_path, monkeypatch):
+    from pythinker_code.tools.memory import Params
+
+    tool = _make_tool(tmp_path, monkeypatch)
+    await tool._store.add("memory", "uses pytest")
+
+    # `list` is read-only: needs no content/old_text and must not rearm injection.
+    rearmed: list[str] = []
+    tool._runtime.rearm_injection = rearmed.append
+    res = await tool(Params(action="list", target="memory"))
+    assert res.is_error is False
+    assert "uses pytest" in res.output
+    assert rearmed == []
+
+
 async def test_memory_tool_missing_content_errors(tmp_path, monkeypatch):
     from pythinker_code.tools.memory import Params
 

tests/ui_and_conv/test_memory_slash.py

@@ -57,6 +57,24 @@ async def _boom(*args, **kwargs):
     assert called["scan"] is False
 
 
+async def test_memory_shows_capacity_line(tmp_path, monkeypatch, capsys):
+    """Bare `/memory` prints a capacity summary so the user can see how full it is."""
+    monkeypatch.setenv("PYTHINKER_SHARE_DIR", str(tmp_path / "share"))
+    from pythinker_code.project_memory import ProjectMemoryStore
+    from pythinker_code.ui.shell import slash
+
+    soul = _fake_soul(tmp_path, consolidation=False)
+    monkeypatch.setattr(slash, "ensure_pythinker_soul", lambda app: soul)
+
+    store = ProjectMemoryStore(soul.runtime.work_dir)
+    await store.add("memory", "uses pytest")
+
+    await _run("", SimpleNamespace())
+    out = capsys.readouterr().out
+    assert "Capacity" in out
+    assert "/5000" in out  # raised project-memory limit
+
+
 async def test_memory_inbox_enabled_invokes_scan(tmp_path, monkeypatch, capsys):
     """With the flag on, `/memory inbox scan` reaches the consolidation path."""
     from pythinker_code.ui.shell import slash