shellbrain 0.1.43__tar.gz → 0.1.45__tar.gz

{shellbrain-0.1.43 → shellbrain-0.1.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.43
+Version: 0.1.45
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{shellbrain-0.1.43 → shellbrain-0.1.45}/app/entrypoints/cli/handlers/human/admin.py

@@ -106,6 +106,18 @@ def run_admin_command(
         print(json.dumps(summary.to_payload(), indent=2, sort_keys=True))
         return 0
 
+    if args.admin_command == "recall":
+        try:
+            if args.recall_command in {"fast", "full"}:
+                mode, path, exists = dependencies.save_recall_mode(args.recall_command)
+            else:
+                mode, path, exists = dependencies.load_recall_mode()
+        except ValueError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+        print(_format_recall_mode(mode=mode, path=path, exists=exists))
+        return 0
+
     repo_root = resolve_admin_repo_root(getattr(args, "repo_root", None))
     if args.admin_command == "install-claude-hook":
         settings_path = dependencies.install_repo_claude_hook(repo_root=repo_root)
@@ -141,3 +153,18 @@ def run_admin_command(
             print(json.dumps({"deleted": deleted}, indent=2, sort_keys=True))
             return 0
     raise ValueError(f"Unsupported admin command: {args.admin_command}")
+
+
+def _format_recall_mode(*, mode: str, path: Path, exists: bool) -> str:
+    if not exists:
+        return "Recall mode: full (default; no override file)"
+    if mode == "fast":
+        return f"Recall mode: fast (deterministic only) from {_display_path(path)}"
+    return f"Recall mode: full (LLM synthesis) from {_display_path(path)}"
+
+
+def _display_path(path: Path) -> str:
+    try:
+        return f"~/{path.expanduser().resolve().relative_to(Path.home())}"
+    except ValueError:
+        return str(path)

{shellbrain-0.1.43 → shellbrain-0.1.45}/app/entrypoints/cli/handlers/human/admin_dependencies.py

@@ -32,3 +32,5 @@ class AdminCommandDependencies(Protocol):
     load_session_state: Callable[..., Any]
     delete_session_state: Callable[..., Any]
     gc_session_state: Callable[..., Any]
+    load_recall_mode: Callable[..., Any]
+    save_recall_mode: Callable[..., Any]

{shellbrain-0.1.43 → shellbrain-0.1.45}/app/entrypoints/cli/parser/builder.py

@@ -291,6 +291,18 @@ _ADMIN_HELP = dedent(
     Example:
       shellbrain init
       shellbrain admin migrate
+      shellbrain admin recall fast
+    """
+)
+
+_RECALL_MODE_HELP = dedent(
+    """\
+    Toggle whether recall uses the inner LLM synthesis agent.
+
+    Examples:
+      shellbrain admin recall fast
+      shellbrain admin recall full
+      shellbrain admin recall status
     """
 )
 
@@ -754,6 +766,19 @@ def build_parser() -> argparse.ArgumentParser:
         epilog=_BACKFILL_TOKEN_USAGE_HELP,
         formatter_class=_HelpFormatter,
     )
+    recall_parser = admin_subparsers.add_parser(
+        "recall",
+        help="Toggle recall between fast deterministic mode and full LLM synthesis.",
+        description="Toggle whether recall uses the inner LLM synthesis agent.",
+        epilog=_RECALL_MODE_HELP,
+        formatter_class=_HelpFormatter,
+    )
+    recall_subparsers = recall_parser.add_subparsers(
+        dest="recall_command", required=True, metavar="recall-command"
+    )
+    recall_subparsers.add_parser("fast", help="Use deterministic-only recall.")
+    recall_subparsers.add_parser("full", help="Use LLM synthesis recall.")
+    recall_subparsers.add_parser("status", help="Print the current recall mode.")
     install_hook_parser = admin_subparsers.add_parser(
         "install-claude-hook",
         help="Install the repo-local Claude hook used for trusted caller identity.",

shellbrain-0.1.45/app/infrastructure/local_state/recall_mode_store.py

@@ -0,0 +1,60 @@
+"""Machine-local recall mode override storage."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import tomllib
+
+from app.infrastructure.local_state.paths import get_shellbrain_home
+
+
+RECALL_MODE_FAST = "fast"
+RECALL_MODE_FULL = "full"
+DEFAULT_RECALL_MODE = RECALL_MODE_FULL
+VALID_RECALL_MODES = {RECALL_MODE_FAST, RECALL_MODE_FULL}
+
+
+def get_recall_mode_path() -> Path:
+    """Return the machine-local recall mode override path."""
+
+    return get_shellbrain_home() / "recall.toml"
+
+
+def load_recall_mode(path: Path | None = None) -> tuple[str, Path, bool]:
+    """Return recall mode, config path, and whether an override file exists."""
+
+    target = path or get_recall_mode_path()
+    try:
+        text = target.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return DEFAULT_RECALL_MODE, target, False
+    try:
+        payload = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise ValueError(f"Invalid recall mode config at {target}: {exc}") from exc
+    if set(payload) != {"mode"}:
+        raise ValueError(
+            f"Invalid recall mode config at {target}: expected only the 'mode' key."
+        )
+    mode = payload.get("mode")
+    if not isinstance(mode, str) or mode not in VALID_RECALL_MODES:
+        raise ValueError(
+            f"Invalid recall mode config at {target}: mode must be 'fast' or 'full'."
+        )
+    return mode, target, True
+
+
+def save_recall_mode(mode: str, path: Path | None = None) -> tuple[str, Path, bool]:
+    """Persist one machine-local recall mode override."""
+
+    if mode not in VALID_RECALL_MODES:
+        raise ValueError("Recall mode must be 'fast' or 'full'.")
+    target = path or get_recall_mode_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(f'mode = "{mode}"\n', encoding="utf-8")
+    try:
+        os.chmod(target, 0o600)
+    except OSError:
+        pass
+    return mode, target, True

{shellbrain-0.1.43 → shellbrain-0.1.45}/app/startup/admin_dependencies.py

@@ -34,3 +34,5 @@ class AdminCommandDependencies:
     load_session_state: Callable[..., Any]
     delete_session_state: Callable[..., Any]
     gc_session_state: Callable[..., Any]
+    load_recall_mode: Callable[..., Any]
+    save_recall_mode: Callable[..., Any]

{shellbrain-0.1.43 → shellbrain-0.1.45}/app/startup/cli.py

@@ -81,6 +81,7 @@ def build_admin_command_dependencies():
     from app.startup import migrations
     from app.startup import model_usage_backfill
     from app.startup.admin_dependencies import AdminCommandDependencies
+    from app.infrastructure.local_state import recall_mode_store
 
     return AdminCommandDependencies(
         upgrade_database=migrations.upgrade_database,
@@ -107,6 +108,8 @@ def build_admin_command_dependencies():
         load_session_state=startup_admin.load_session_state,
         delete_session_state=startup_admin.delete_session_state,
         gc_session_state=startup_admin.gc_session_state,
+        load_recall_mode=recall_mode_store.load_recall_mode,
+        save_recall_mode=recall_mode_store.save_recall_mode,
     )
 
 

{shellbrain-0.1.43 → shellbrain-0.1.45}/app/startup/internal_agents.py

@@ -21,6 +21,10 @@ from app.core.ports.host_apps.inner_agents import (
 )
 from app.infrastructure.host_apps.inner_agents.claude_cli import ClaudeCliInnerAgentRunner
 from app.infrastructure.host_apps.inner_agents.codex_cli import CodexCliInnerAgentRunner
+from app.infrastructure.local_state.recall_mode_store import (
+    RECALL_MODE_FAST,
+    load_recall_mode,
+)
 from app.startup.config import get_config_provider
 from app.startup.internal_agent_config import InternalAgentsConfig
 
@@ -43,7 +47,7 @@ def get_build_context_settings() -> InnerAgentSettings:
     """Return typed settings for the read-only build_context agent."""
 
     config = get_internal_agents_config()
-    return _resolve_settings(config, config.build_context)
+    return _resolve_build_context_settings(config)
 
 
 def get_build_knowledge_settings() -> BuildKnowledgeSettings:
@@ -71,7 +75,10 @@ def get_build_context_inner_agent_runner() -> IInnerAgentRunner | None:
     """Return the configured build_context provider adapter."""
 
     config = get_internal_agents_config()
-    return _runner_for(config, config.build_context)
+    settings = _resolve_build_context_settings(config)
+    if settings.strategy == "deterministic_only":
+        return None
+    return _runner_for(config, settings)
 
 
 def get_build_knowledge_inner_agent_runner() -> IBuildKnowledgeAgentRunner | None:
@@ -138,6 +145,16 @@ def _resolve_settings(
     )
 
 
+def _resolve_build_context_settings(config: InternalAgentsConfig) -> InnerAgentSettings:
+    settings = _resolve_settings(config, config.build_context)
+    mode, _path, exists = load_recall_mode()
+    if not exists:
+        return settings
+    if mode == RECALL_MODE_FAST:
+        return settings.model_copy(update={"strategy": "deterministic_only"})
+    return settings.model_copy(update={"strategy": "deterministic_synthesis"})
+
+
 def _select_provider(
     config: InternalAgentsConfig,
     requested_provider: str,

shellbrain-0.1.45/onboarding_assets/claude/CLAUDE.md

@@ -0,0 +1,40 @@
+## Shellbrain
+
+Use Shellbrain for targeted recall during agent work.
+
+Keep this tuple in mind:
+
+`goal | surface | obstacle | hypothesis`
+
+Emit one `SB:` line when the tuple changes or you hit a boundary state:
+
+- goal, surface, obstacle, or hypothesis changed
+- same approach failed twice
+- an error repeats
+- you are about to make an evidence-bearing decision
+- you switch files, subsystems, or strategy
+- you are closing out
+
+If prior context may help:
+
+`SB: recall | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
+
+Then run:
+
+```bash
+shellbrain recall --json '{"query":"<targeted question>","current_problem":{"goal":"<goal>","surface":"<surface>","obstacle":"<obstacle>","hypothesis":"<hypothesis or none yet>"}}'
+```
+
+If recall would not help:
+
+`SB: skip | same signature | <one-line reason>`
+
+Then continue. Do not call recall reflexively.
+
+Use `shellbrain recall` for normal task context. Use `shellbrain teach` only when the user explicitly asks you to store or teach Shellbrain something.
+
+If you changed any files since your last user-facing response, run `shellbrain snapshot` exactly once after validation and immediately before your next user-facing response. Do this on every response cycle where files changed; skip only when no files changed.
+
+Do not call `shellbrain read`, `shellbrain events`, `shellbrain memory`, `shellbrain concept`, or `shellbrain scenario`.
+
+Use the installed `shellbrain` skill for the detailed recall workflow.

shellbrain-0.1.45/onboarding_assets/codex/AGENTS.md

@@ -0,0 +1,40 @@
+## Shellbrain
+
+Use Shellbrain for targeted recall during agent work.
+
+Keep this tuple in mind:
+
+`goal | surface | obstacle | hypothesis`
+
+Emit one `SB:` line when the tuple changes or you hit a boundary state:
+
+- goal, surface, obstacle, or hypothesis changed
+- same approach failed twice
+- an error repeats
+- you are about to make an evidence-bearing decision
+- you switch files, subsystems, or strategy
+- you are closing out
+
+If prior context may help:
+
+`SB: recall | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
+
+Then run:
+
+```bash
+shellbrain recall --json '{"query":"<targeted question>","current_problem":{"goal":"<goal>","surface":"<surface>","obstacle":"<obstacle>","hypothesis":"<hypothesis or none yet>"}}'
+```
+
+If recall would not help:
+
+`SB: skip | same signature | <one-line reason>`
+
+Then continue. Do not call recall reflexively.
+
+Use `shellbrain recall` for normal task context. Use `shellbrain teach` only when the user explicitly asks you to store or teach Shellbrain something.
+
+If you changed any files since your last user-facing response, run `shellbrain snapshot` exactly once after validation and immediately before your next user-facing response. Do this on every response cycle where files changed; skip only when no files changed.
+
+Do not call `shellbrain read`, `shellbrain events`, `shellbrain memory`, `shellbrain concept`, or `shellbrain scenario`.
+
+Use the installed `shellbrain` skill for the detailed recall workflow.

{shellbrain-0.1.43 → shellbrain-0.1.45}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shellbrain"
-version = "0.1.43"
+version = "0.1.45"
 description = "Repo-scoped Shellbrain CLI with explicit evidence-backed writes."
 readme = "README.md"
 requires-python = ">=3.11"

{shellbrain-0.1.43 → shellbrain-0.1.45}/shellbrain.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.43
+Version: 0.1.45
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{shellbrain-0.1.43 → shellbrain-0.1.45}/shellbrain.egg-info/SOURCES.txt

@@ -343,6 +343,7 @@ app/infrastructure/local_state/init_lock.py
 app/infrastructure/local_state/machine_config_store.py
 app/infrastructure/local_state/operation_registration.py
 app/infrastructure/local_state/paths.py
+app/infrastructure/local_state/recall_mode_store.py
 app/infrastructure/local_state/repo_registration_store.py
 app/infrastructure/local_state/session_state_file_store.py
 app/infrastructure/local_state/shadow_git_store.py

shellbrain-0.1.43/onboarding_assets/claude/CLAUDE.md

@@ -1,52 +0,0 @@
-## Shellbrain
-
-You have a persistent memory system called Shellbrain. This section exists to make you remember to use it at the right moments.
-
-### The Core Habit
-
-As you work, maintain a mental summary of your current subproblem as:
-
-`goal | surface | obstacle | hypothesis`
-
-When that tuple changes materially, or you hit a boundary state, pause and say one `SB:` line out loud by actually generating it as output. This keeps Shellbrain in your local attention so you can decide whether recall would help.
-
-Boundary states:
-
-- The goal, surface, obstacle, or hypothesis changed.
-- The same approach failed twice.
-- An error is repeating.
-- You are about to make an evidence-bearing decision.
-- You are switching files, subsystems, or implementation strategy.
-- You are closing out a task.
-
-### What To Say
-
-If prior context might help:
-
-`SB: recall | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
-
-Then call Shellbrain recall:
-
-```bash
-shellbrain recall --json '{"query":"<targeted question>","current_problem":{"goal":"<goal>","surface":"<surface>","obstacle":"<obstacle>","hypothesis":"<hypothesis or none yet>"}}'
-```
-
-If the tuple has not changed and there is no new evidence, failure, or uncertainty:
-
-`SB: skip | same signature | <one-line reason>`
-
-Then continue. Do not call recall reflexively.
-
-### Worker Boundary
-
-As the working agent, use `shellbrain recall` for normal task context. Use `shellbrain teach` only when the user explicitly asks you to store or teach Shellbrain something.
-
-If you changed any files since your last user-facing response, run `shellbrain snapshot` exactly once after validation and immediately before your next user-facing response. Do this on every response cycle where files changed; skip only when no files changed.
-
-Do not call `shellbrain read`, `shellbrain events`, `shellbrain memory`, `shellbrain concept`, or `shellbrain scenario`.
-
-Shellbrain's internal agents handle raw retrieval, synthesis, memory writing, concept updates, scenario recording, and teach consolidation.
-
-### Reference
-
-Use the installed `shellbrain` skill for the detailed recall workflow.

shellbrain-0.1.43/onboarding_assets/codex/AGENTS.md

@@ -1,52 +0,0 @@
-## Shellbrain
-
-You have a persistent memory system called Shellbrain. This section exists to make you remember to use it at the right moments.
-
-### The Core Habit
-
-As you work, maintain a mental summary of your current subproblem as:
-
-`goal | surface | obstacle | hypothesis`
-
-When that tuple changes materially, or you hit a boundary state, pause and say one `SB:` line out loud by actually generating it as output. This keeps Shellbrain in your local attention so you can decide whether recall would help.
-
-Boundary states:
-
-- The goal, surface, obstacle, or hypothesis changed.
-- The same approach failed twice.
-- An error is repeating.
-- You are about to make an evidence-bearing decision.
-- You are switching files, subsystems, or implementation strategy.
-- You are closing out a task.
-
-### What To Say
-
-If prior context might help:
-
-`SB: recall | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
-
-Then call Shellbrain recall:
-
-```bash
-shellbrain recall --json '{"query":"<targeted question>","current_problem":{"goal":"<goal>","surface":"<surface>","obstacle":"<obstacle>","hypothesis":"<hypothesis or none yet>"}}'
-```
-
-If the tuple has not changed and there is no new evidence, failure, or uncertainty:
-
-`SB: skip | same signature | <one-line reason>`
-
-Then continue. Do not call recall reflexively.
-
-### Worker Boundary
-
-As the working agent, use `shellbrain recall` for normal task context. Use `shellbrain teach` only when the user explicitly asks you to store or teach Shellbrain something.
-
-If you changed any files since your last user-facing response, run `shellbrain snapshot` exactly once after validation and immediately before your next user-facing response. Do this on every response cycle where files changed; skip only when no files changed.
-
-Do not call `shellbrain read`, `shellbrain events`, `shellbrain memory`, `shellbrain concept`, or `shellbrain scenario`.
-
-Shellbrain's internal agents handle raw retrieval, synthesis, memory writing, concept updates, scenario recording, and teach consolidation.
-
-### Reference
-
-Use the installed `shellbrain` skill for the detailed recall workflow.