shellbrain 0.1.46__tar.gz → 0.1.48__tar.gz

{shellbrain-0.1.46 → shellbrain-0.1.48}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.46
+Version: 0.1.48
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -71,8 +71,10 @@ The episodic layer is truth. Empirical memory extracts. Concept memory abstracts
 
 **Working agents call `shellbrain recall`.** That is the normal interface they have to think about. One command, **one _carefully curated_ compact brief**, with sources cited.
 
+Recall receives only the quoted query, so include the relevant task, failure, subsystem, or decision naturally in the question.
+
 ```bash
-shellbrain recall --json '{"query":"What is ShellBrain and how does it help a working coding agent?","current_problem":{"goal":"understand ShellBrain","surface":"README","obstacle":"new readers do not know the product yet","hypothesis":"a real recall brief should show what agents get back"}}'
+shellbrain recall "What is ShellBrain, and how does it help a working coding agent?"
 ```
 
 Response shape:

{shellbrain-0.1.46 → shellbrain-0.1.48}/README.md

@@ -57,8 +57,10 @@ The episodic layer is truth. Empirical memory extracts. Concept memory abstracts
 
 **Working agents call `shellbrain recall`.** That is the normal interface they have to think about. One command, **one _carefully curated_ compact brief**, with sources cited.
 
+Recall receives only the quoted query, so include the relevant task, failure, subsystem, or decision naturally in the question.
+
 ```bash
-shellbrain recall --json '{"query":"What is ShellBrain and how does it help a working coding agent?","current_problem":{"goal":"understand ShellBrain","surface":"README","obstacle":"new readers do not know the product yet","hypothesis":"a real recall brief should show what agents get back"}}'
+shellbrain recall "What is ShellBrain, and how does it help a working coding agent?"
 ```
 
 Response shape:

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/core/ports/host_apps/inner_agents.py

@@ -34,7 +34,6 @@ class InnerAgentRunRequest(_StrictModel):
     max_private_reads: int = Field(default=0, ge=0, le=10)
     max_brief_tokens: int | None = Field(default=None, ge=1, le=100_000)
     query: str = Field(min_length=1)
-    current_problem: dict[str, str]
     repo_root: str | None = None
     synthesis_only: bool = False
     deterministic_pack: dict[str, Any] | None = None

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/core/use_cases/retrieval/build_context/execute.py

@@ -160,7 +160,6 @@ def _inner_agent_request(
         max_private_reads=settings.max_private_reads,
         max_brief_tokens=settings.max_brief_tokens,
         query=request.query,
-        current_problem=request.current_problem.model_dump(mode="python"),
         repo_root=repo_root,
         synthesis_only=synthesis_only,
         deterministic_pack=deterministic_pack,

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/core/use_cases/retrieval/deterministic_graph_recall.py

@@ -55,7 +55,6 @@ _CONCEPT_HARD_CAP = 8
 _RELATION_NEIGHBOR_CAP = 4
 _HIGH_SIGNAL_RELATIONS = {"depends_on", "constrains", "precedes", "contains"}
 _HIGH_SIGNAL_CLAIMS = {"invariant", "failure_mode", "usage_note", "behavior"}
-_PLACEHOLDER_VALUES = {"none", "none yet", "n/a", "na", "unknown", "not sure"}
 
 
 @dataclass(frozen=True)
@@ -142,7 +141,6 @@ def build_deterministic_graph_pack(
         "strategy": "deterministic_graph",
         "request": {
             "query": request.query,
-            "current_problem": request.current_problem.model_dump(mode="python"),
         },
         "query_lanes": [
             {"lane": lane.name, "query": lane.query, "terms": list(lane.terms)}
@@ -320,10 +318,9 @@ def source_items_from_graph_pack(pack: dict[str, Any]) -> list[dict[str, Any]]:
 
 def _build_query_lanes(request: MemoryRecallRequest) -> list[_QueryLane]:
     original = _lane("original", request.query)
-    current_problem = _current_problem_lane(request)
     identifiers = _identifier_lane(request)
     traps = _prior_cases_lane(request)
-    lanes = [lane for lane in (original, current_problem, identifiers, traps) if lane]
+    lanes = [lane for lane in (original, identifiers, traps) if lane]
     deduped: list[_QueryLane] = []
     seen_queries: set[str] = set()
     for lane in lanes:
@@ -343,24 +340,13 @@ def _lane(name: str, query: str) -> _QueryLane | None:
     return _QueryLane(name=name, query=text, terms=terms)
 
 
-def _current_problem_lane(request: MemoryRecallRequest) -> _QueryLane | None:
-    problem = request.current_problem.model_dump(mode="python")
-    parts = [
-        value
-        for key in ("surface", "obstacle", "hypothesis", "goal")
-        if _useful_problem_part(value := str(problem.get(key) or ""))
-    ]
-    return _lane("current_problem", " ".join(parts))
-
-
 def _identifier_lane(request: MemoryRecallRequest) -> _QueryLane | None:
-    problem_text = " ".join(request.current_problem.model_dump(mode="python").values())
-    identifiers = _extract_identifiers(f"{request.query} {problem_text}")
+    identifiers = _extract_identifiers(request.query)
     return _lane("identifiers", " ".join(identifiers))
 
 
 def _prior_cases_lane(request: MemoryRecallRequest) -> _QueryLane | None:
-    terms = list(dict.fromkeys(_tokenize(f"{request.query} {request.current_problem.obstacle}")))
+    terms = list(dict.fromkeys(_tokenize(request.query)))
     strongest = " ".join(terms[:8])
     if not strongest:
         return None
@@ -371,7 +357,7 @@ def _prior_cases_lane(request: MemoryRecallRequest) -> _QueryLane | None:
 
 
 def _broad_domain_lane(request: MemoryRecallRequest) -> _QueryLane | None:
-    terms = _tokenize(f"{request.current_problem.surface} {request.current_problem.goal}")
+    terms = _tokenize(request.query)
     if not terms:
         return None
     return _lane("broad_domain", " ".join(dict.fromkeys(terms[:8])))
@@ -1392,11 +1378,6 @@ def _tokenize(text: str) -> tuple[str, ...]:
     return tuple(re.findall(r"[a-z0-9_./:-]+", text.lower()))
 
 
-def _useful_problem_part(value: str) -> bool:
-    text = value.strip().lower()
-    return bool(text and text not in _PLACEHOLDER_VALUES)
-
-
 def _dedupe_reasons(reasons: Iterable[dict[str, Any]]) -> list[dict[str, Any]]:
     seen: set[str] = set()
     deduped = []

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/core/use_cases/retrieval/recall/__init__.py

@@ -1,14 +1,10 @@
 """Memory recall use case."""
 
-from app.core.use_cases.retrieval.recall.request import (
-    MemoryRecallRequest,
-    RecallCurrentProblem,
-)
+from app.core.use_cases.retrieval.recall.request import MemoryRecallRequest
 from app.core.use_cases.retrieval.recall.result import RecallMemoryResult
 
 __all__ = [
     "MemoryRecallRequest",
-    "RecallCurrentProblem",
     "RecallMemoryResult",
     "execute_recall_memory",
 ]

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/core/use_cases/retrieval/recall/request.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-from typing import Literal
-
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from app.core.entities.ids import RepoId
@@ -24,28 +22,11 @@ def _normalize_repo_id(value: RepoId) -> RepoId:
     return RepoId(_normalize_required_string(str(value), field_name="repo_id"))
 
 
-class RecallCurrentProblem(_StrictModel):
-    """Required worker problem context for recall synthesis."""
-
-    goal: str = Field(min_length=1)
-    surface: str = Field(min_length=1)
-    obstacle: str = Field(min_length=1)
-    hypothesis: str = Field(min_length=1)
-
-    @field_validator("goal", "surface", "obstacle", "hypothesis")
-    @classmethod
-    def _validate_non_blank(cls, value: str) -> str:
-        return _normalize_required_string(value, field_name="current_problem fields")
-
-
 class MemoryRecallRequest(_StrictModel):
     """Canonical recall request payload."""
 
-    op: Literal["recall"] = "recall"
     repo_id: RepoId
     query: str = Field(min_length=1)
-    limit: int | None = Field(default=None, ge=1, le=100)
-    current_problem: RecallCurrentProblem
 
     @field_validator("repo_id")
     @classmethod

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/entrypoints/cli/parser/builder.py

@@ -45,7 +45,8 @@ _TOP_LEVEL_HELP = dedent(
         - Use `shellbrain recall` for normal task context.
         - Use `shellbrain teach` only when the user explicitly asks 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.
-        - Send a concrete `query` plus required `current_problem`.
+        - Send one concrete natural-language query.
+        - Recall receives only this query, so include relevant task context naturally.
         - Avoid generic prompts like "what should I know about this repo?"
 
       Internal recall agents:
@@ -74,7 +75,7 @@ _TOP_LEVEL_HELP = dedent(
       shellbrain admin migrate
 
       Working agents:
-      shellbrain recall --json '{"query":"What context matters for this migration lock timeout?","current_problem":{"goal":"fix migration locking","surface":"db admin","obstacle":"lock timeout","hypothesis":"missing timeout guard"}}'
+      shellbrain recall "What context matters for this migration lock timeout?"
       shellbrain teach --json '{"text":"In this repo, startup wires dependencies but should not own workflow behavior.","current_problem":{"goal":"record architecture preference","surface":"startup and clean architecture","obstacle":"agents may put behavior in startup","hypothesis":"teach should become a durable preference or concept claim"}}'
       shellbrain snapshot
 
@@ -158,14 +159,13 @@ _RECALL_HELP = dedent(
     This is the normal working-agent interface. Working agents should call
     `recall`, not internal commands like `read`, `events`, or `concept show`.
 
-    Requires `query` and `current_problem`.
-    `current_problem` must include non-empty `goal`, `surface`, `obstacle`, and
-    `hypothesis`; use an explicit value like "none yet" when there is no hypothesis.
-    Accepts optional `limit`.
+    Pass one self-contained natural-language query naming the failure mode,
+    subsystem, decision, file area, or constraint that matters. Recall receives
+    only this query, so include relevant task context naturally.
     It does not mutate memories, concepts, utility observations, or problem runs.
 
     Example:
-      shellbrain recall --json '{"query":"What context matters for this migration lock timeout?","current_problem":{"goal":"fix migration locking","surface":"db admin","obstacle":"Docker unavailable","hypothesis":"none yet"}}'
+      shellbrain recall "What context matters for this migration lock timeout?"
     """
 )
 
@@ -565,7 +565,7 @@ def build_parser() -> argparse.ArgumentParser:
         formatter_class=_HelpFormatter,
     )
     _add_repo_context_arguments(recall_parser, suppress_default=True)
-    _add_payload_arguments(recall_parser)
+    recall_parser.add_argument("query", help="Natural-language recall query.")
 
     teach_parser = subparsers.add_parser(
         "teach",

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/entrypoints/cli/presenters/init.py

@@ -34,7 +34,7 @@ def render_success_lines(
             "Repo registration: deferred until first Shellbrain use inside a repo."
         )
         lines.append(
-            'Next: from inside a repo, run shellbrain recall --json \'{"query":"What prior Shellbrain context matters for this task?","current_problem":{"goal":"start work","surface":"repo session","obstacle":"none yet","hypothesis":"none yet"}}\''
+            'Next: from inside a repo, run shellbrain recall "What prior Shellbrain context matters for this task?"'
         )
     else:
         lines.insert(1, f"Repo: {registration.repo_id}")
@@ -44,7 +44,7 @@ def render_success_lines(
                 "Repo identity is weak-local and will change if this directory moves. Use --repo-id for a durable override.",
             )
         lines.append(
-            'Next: shellbrain recall --json \'{"query":"What prior Shellbrain context matters for this task?","current_problem":{"goal":"start work","surface":"repo session","obstacle":"none yet","hypothesis":"none yet"}}\''
+            'Next: shellbrain recall "What prior Shellbrain context matters for this task?"'
         )
     lines.extend(notes)
     return lines

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/entrypoints/cli/request_parsing/payload_validation.py

@@ -84,37 +84,6 @@ class AgentReadRequest(StrictBaseModel):
         return value
 
 
-class AgentRecallCurrentProblem(StrictBaseModel):
-    """Agent-facing current-problem context for recall synthesis."""
-
-    goal: str = Field(min_length=1)
-    surface: str = Field(min_length=1)
-    obstacle: str = Field(min_length=1)
-    hypothesis: str = Field(min_length=1)
-
-    @field_validator("goal", "surface", "obstacle", "hypothesis")
-    @classmethod
-    def _validate_non_blank(cls, value: str) -> str:
-        """Require every problem context field to be explicit."""
-
-        return _normalize_required_string(
-            value, field_name="current_problem fields"
-        )
-
-
-class AgentRecallRequest(StrictBaseModel):
-    """Agent-facing recall payload with worker problem context."""
-
-    query: str = Field(min_length=1)
-    limit: int | None = Field(default=None, ge=1, le=100)
-    current_problem: AgentRecallCurrentProblem
-
-    @field_validator("query")
-    @classmethod
-    def _validate_query(cls, value: str) -> str:
-        return _normalize_required_string(value, field_name="query")
-
-
 class AgentTeachRequest(StrictBaseModel):
     """Worker-facing payload for explicit user teaching."""
 
@@ -282,17 +251,6 @@ def validate_read_schema(
         return None, _format_validation_errors(exc)
 
 
-def validate_recall_schema(
-    payload: dict[str, Any],
-) -> tuple[AgentRecallRequest | None, list[ErrorDetail]]:
-    """Validate and parse agent recall payloads into the minimal recall contract."""
-
-    try:
-        return AgentRecallRequest.model_validate(payload), []
-    except ValidationError as exc:
-        return None, _format_validation_errors(exc)
-
-
 def validate_events_schema(
     payload: dict[str, Any],
 ) -> tuple[AgentEventsRequest | None, list[ErrorDetail]]:

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/entrypoints/cli/request_parsing/retrieval.py

@@ -9,7 +9,6 @@ from app.entrypoints.cli.request_parsing.payload_validation import (
     validate_internal_read_contract,
     validate_internal_recall_contract,
     validate_read_schema,
-    validate_recall_schema,
 )
 from app.entrypoints.cli.request_parsing.prepared import (
     PreparedOperationRequest,
@@ -67,14 +66,7 @@ def prepare_recall_request(
 ) -> PreparedOperationRequest[MemoryRecallRequest]:
     """Validate and hydrate one raw recall payload."""
 
-    agent_request, errors = validate_recall_schema(payload)
-    if errors:
-        return PreparedOperationRequest(
-            request=None, errors=errors, error_stage="schema_validation"
-        )
-    assert agent_request is not None
-    hydrated = agent_request.model_dump(mode="python", exclude_none=True)
-    hydrated.setdefault("op", "recall")
+    hydrated = dict(payload)
     hydrated.setdefault("repo_id", inferred_repo_id)
     request, contract_errors = validate_internal_recall_contract(hydrated)
     return PreparedOperationRequest(

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/entrypoints/cli/runner.py

@@ -122,13 +122,14 @@ def main(
             repo_root_arg=getattr(args, "repo_root", None),
             repo_id_arg=getattr(args, "repo_id", None),
         )
-        payload = (
-            {}
-            if command == "snapshot"
-            else _load_payload(
+        if command == "snapshot":
+            payload = {}
+        elif command == "recall":
+            payload = {"query": args.query}
+        else:
+            payload = _load_payload(
                 getattr(args, "json_text", None), getattr(args, "json_file", None)
             )
-        )
     except ValueError as exc:
         parser.error(str(exc))
         return 2

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/infrastructure/host_apps/inner_agents/prompt.py

@@ -83,18 +83,17 @@ admin/init/upgrade/metrics, filesystem writes, settings writes, and direct DB
 writes.
 
 # PROTOCOL
-1. Read the payload: `query`, `current_problem`, `repo_root`, and budgets.
+1. Read the payload: `query`, `repo_root`, and budgets. Treat `query` as the
+   complete worker context.
    Use the repo-root-prefixed commands from the payload whenever `repo_root` is
    provided. Do not omit `--repo-root` in nested Codex.
 2. Run events first:
    ```bash
    shellbrain --no-sync --repo-root "<repo_root>" events --json '{"limit":10}'
    ```
-3. Build a compact search text from the query and useful parts of
-   current_problem.goal, surface, obstacle, and hypothesis. Omit placeholders
-   such as "none yet". Prefer concrete error terms, domain nouns,
-   files/symbols, and the actual obstacle over generic goal text. Use recent
-   events to sharpen the query when they reveal better terms.
+3. Build a compact search text from the query. Prefer concrete error terms,
+   domain nouns, files/symbols, and the actual obstacle over generic wording.
+   Use recent events to sharpen the query when they reveal better terms.
 4. Run at least one targeted read:
    ```bash
    shellbrain --no-sync --repo-root "<repo_root>" read --json '{"query":"<combined search text>","kinds":["problem","solution","failed_tactic","fact","preference","change"]}'
@@ -114,7 +113,7 @@ writes.
    ```
    If multiple concepts match, inspect at most the few most relevant within
    budget. Prefer concepts whose claims, groundings, or memory links connect
-   directly to current_problem.surface or current_problem.obstacle. Mention
+   directly to the query. Mention
    competing or ambiguous concepts only when the ambiguity affects the worker.
 6. Run extra reads only when they are likely to improve the brief: events reveal
    a sharper query, concept details suggest a related term, the first read was
@@ -180,7 +179,7 @@ You are Shellbrain build_context_synthesizer.
 # JOB
 Synthesize a compact operational recall brief from the deterministic recall
 graph pack. Do not request more data. Do not run commands. Do not inspect files.
-Do not invent facts. Use only the pack.
+Do not invent facts. Use only the pack. The query is the complete worker request.
 
 Your job is not to summarize everything. Your job is to tell the working coding
 agent what prior knowledge changes what it should do next.
@@ -867,7 +866,6 @@ def render_build_context_prompt(request: InnerAgentRunRequest) -> str:
     shellbrain = _shellbrain_command(request.repo_root, no_sync=True)
     payload = {
         "query": request.query,
-        "current_problem": request.current_problem,
         "repo_root": request.repo_root,
         "budgets": {
             "max_private_reads": request.max_private_reads,
@@ -938,7 +936,6 @@ def render_build_context_synthesis_prompt(request: InnerAgentRunRequest) -> str:
 
     payload = {
         "query": request.query,
-        "current_problem": request.current_problem,
         "budgets": {
             "max_brief_tokens": request.max_brief_tokens,
         },

{shellbrain-0.1.46 → shellbrain-0.1.48}/app/settings/internal-agents/defaults.yaml

@@ -3,7 +3,7 @@ build_context:
   strategy: deterministic_synthesis
   provider: auto
   model: gpt-5.4-mini
-  reasoning: medium
+  reasoning: low
   timeout_seconds: 90
   max_private_reads: 3
   max_brief_tokens: 1800

{shellbrain-0.1.46 → shellbrain-0.1.48}/onboarding_assets/claude/CLAUDE.md

@@ -22,9 +22,11 @@ If prior context may help:
 Then run:
 
 ```bash
-shellbrain recall --json '{"query":"<targeted question>","current_problem":{"goal":"<goal>","surface":"<surface>","obstacle":"<obstacle>","hypothesis":"<hypothesis or none yet>"}}'
+shellbrain recall "<targeted natural-language question>"
 ```
 
+Recall receives only this query, so include relevant task context naturally in the question.
+
 If recall would not help:
 
 `SB: skip | same signature | <one-line reason>`

{shellbrain-0.1.46 → shellbrain-0.1.48}/onboarding_assets/claude/skills/shellbrain/SKILL.md

@@ -12,7 +12,7 @@ Shellbrain is a persistent memory system for agent work.
 As the working agent, your interface is:
 
 ```bash
-shellbrain recall
+shellbrain recall "<targeted natural-language question>"
 ```
 
 Recall returns a compact brief synthesized from prior memories, concepts, scenarios, and recent episode context. It is meant to reduce wasted exploration and help you decide where to look next.
@@ -43,7 +43,7 @@ Use this order:
 
 1. If Shellbrain is missing or broken, run `shellbrain admin doctor`.
 2. If doctor says repair is needed, run `shellbrain init`.
-3. Otherwise, use `shellbrain recall` with a targeted query and `current_problem`.
+3. Otherwise, use `shellbrain recall` with one targeted natural-language query.
 
 If `shellbrain` is not found, do a one-time PATH check:
 
@@ -105,14 +105,12 @@ If recall would not add information:
 
 Then continue.
 
-## Recall Payload
+## Recall Query
 
-`current_problem` is required. All four fields must be non-empty strings.
-
-If you do not have a hypothesis yet, use `"none yet"`.
+Pass one self-contained question as a quoted positional argument. Recall receives only this query, so include relevant task context naturally.
 
 ```bash
-shellbrain recall --json '{"query":"Have we seen this failure mode or subsystem before?","current_problem":{"goal":"fix failing architecture guardrail test","surface":"tests/config/test_architecture_boundaries.py and app layer imports","obstacle":"entrypoint handler appears to import startup wiring","hypothesis":"dependency shape should move out of startup"}}'
+shellbrain recall "Have we seen this architecture guardrail failure or subsystem boundary before?"
 ```
 
 ## Teach Payload
@@ -140,15 +138,15 @@ Good recall queries are concrete. Name the failure mode, subsystem, decision, fi
 Good examples:
 
 ```bash
-shellbrain recall --json '{"query":"Have we seen this migration lock timeout before?","current_problem":{"goal":"fix migration test failure","surface":"database migrations and schema setup","obstacle":"migration blocks waiting on lock","hypothesis":"a previous test leaves a transaction open"}}'
+shellbrain recall "I'm debugging a migration lock timeout. What prior context matters?"
 ```
 
 ```bash
-shellbrain recall --json '{"query":"What architectural constraints matter before moving this CLI handler?","current_problem":{"goal":"move CLI handler without breaking clean architecture","surface":"entrypoints, startup, and handler dependency wiring","obstacle":"handler currently imports startup types","hypothesis":"startup should construct dependencies but handler should receive protocols"}}'
+shellbrain recall "What architectural constraints matter before moving this CLI handler?"
 ```
 
 ```bash
-shellbrain recall --json '{"query":"What user preferences matter for this refactor?","current_problem":{"goal":"clean up Shellbrain onboarding assets","surface":"AGENTS.md and shellbrain skill","obstacle":"old guidance teaches internal commands to workers","hypothesis":"worker guidance should only teach recall"}}'
+shellbrain recall "What user preferences matter while simplifying Shellbrain onboarding assets?"
 ```
 
 Avoid vague queries:

{shellbrain-0.1.46 → shellbrain-0.1.48}/onboarding_assets/codex/AGENTS.md

@@ -22,9 +22,11 @@ If prior context may help:
 Then run:
 
 ```bash
-shellbrain recall --json '{"query":"<targeted question>","current_problem":{"goal":"<goal>","surface":"<surface>","obstacle":"<obstacle>","hypothesis":"<hypothesis or none yet>"}}'
+shellbrain recall "<targeted natural-language question>"
 ```
 
+Recall receives only this query, so include relevant task context naturally in the question.
+
 If recall would not help:
 
 `SB: skip | same signature | <one-line reason>`

{shellbrain-0.1.46/onboarding_assets/cursor/skills → shellbrain-0.1.48/onboarding_assets/codex}/shellbrain/SKILL.md

@@ -12,7 +12,7 @@ Shellbrain is a persistent memory system for agent work.
 As the working agent, your interface is:
 
 ```bash
-shellbrain recall
+shellbrain recall "<targeted natural-language question>"
 ```
 
 Recall returns a compact brief synthesized from prior memories, concepts, scenarios, and recent episode context. It is meant to reduce wasted exploration and help you decide where to look next.
@@ -43,7 +43,7 @@ Use this order:
 
 1. If Shellbrain is missing or broken, run `shellbrain admin doctor`.
 2. If doctor says repair is needed, run `shellbrain init`.
-3. Otherwise, use `shellbrain recall` with a targeted query and `current_problem`.
+3. Otherwise, use `shellbrain recall` with one targeted natural-language query.
 
 If `shellbrain` is not found, do a one-time PATH check:
 
@@ -105,14 +105,12 @@ If recall would not add information:
 
 Then continue.
 
-## Recall Payload
+## Recall Query
 
-`current_problem` is required. All four fields must be non-empty strings.
-
-If you do not have a hypothesis yet, use `"none yet"`.
+Pass one self-contained question as a quoted positional argument. Recall receives only this query, so include relevant task context naturally.
 
 ```bash
-shellbrain recall --json '{"query":"Have we seen this failure mode or subsystem before?","current_problem":{"goal":"fix failing architecture guardrail test","surface":"tests/config/test_architecture_boundaries.py and app layer imports","obstacle":"entrypoint handler appears to import startup wiring","hypothesis":"dependency shape should move out of startup"}}'
+shellbrain recall "Have we seen this architecture guardrail failure or subsystem boundary before?"
 ```
 
 ## Teach Payload
@@ -140,15 +138,15 @@ Good recall queries are concrete. Name the failure mode, subsystem, decision, fi
 Good examples:
 
 ```bash
-shellbrain recall --json '{"query":"Have we seen this migration lock timeout before?","current_problem":{"goal":"fix migration test failure","surface":"database migrations and schema setup","obstacle":"migration blocks waiting on lock","hypothesis":"a previous test leaves a transaction open"}}'
+shellbrain recall "I'm debugging a migration lock timeout. What prior context matters?"
 ```
 
 ```bash
-shellbrain recall --json '{"query":"What architectural constraints matter before moving this CLI handler?","current_problem":{"goal":"move CLI handler without breaking clean architecture","surface":"entrypoints, startup, and handler dependency wiring","obstacle":"handler currently imports startup types","hypothesis":"startup should construct dependencies but handler should receive protocols"}}'
+shellbrain recall "What architectural constraints matter before moving this CLI handler?"
 ```
 
 ```bash
-shellbrain recall --json '{"query":"What user preferences matter for this refactor?","current_problem":{"goal":"clean up Shellbrain onboarding assets","surface":"AGENTS.md and shellbrain skill","obstacle":"old guidance teaches internal commands to workers","hypothesis":"worker guidance should only teach recall"}}'
+shellbrain recall "What user preferences matter while simplifying Shellbrain onboarding assets?"
 ```
 
 Avoid vague queries:
@@ -191,3 +189,7 @@ shellbrain scenario record
 Those are internal-agent commands.
 
 Do not manually write memories at closeout. Shellbrain's knowledge-builder agent consolidates episodes after the session lifecycle.
+
+## Resources
+
+- Read [references/session-workflow.md](references/session-workflow.md) for the detailed recall cadence and attention habit.

{shellbrain-0.1.46 → shellbrain-0.1.48}/onboarding_assets/codex/shellbrain/references/session-workflow.md

@@ -7,7 +7,7 @@ Shellbrain is persistent memory for agent work. The working agent does not brows
 The working-agent interface is:
 
 ```bash
-shellbrain recall
+shellbrain recall "<targeted natural-language question>"
 ```
 
 Recall asks Shellbrain's internal recall agent to inspect relevant memories, concepts, scenarios, and recent episode context, then return a compact brief for the current problem.
@@ -84,7 +84,7 @@ If prior context might help:
 
 `SB: recall | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
 
-Then call recall with a targeted query and `current_problem`.
+Then call recall with one targeted natural-language query.
 
 If recall would not add information:
 
@@ -92,19 +92,14 @@ If recall would not add information:
 
 Then continue. Do not call recall reflexively.
 
-## Recall Payload
+## Recall Query
 
-`current_problem` is required. It has four required non-empty fields:
-
-- `goal`: what you are trying to accomplish
-- `surface`: the code, subsystem, behavior, or decision area
-- `obstacle`: what is blocking or uncertain
-- `hypothesis`: your current theory, or `"none yet"`
+Pass one self-contained question as a quoted positional argument. Recall receives only this query, so include relevant task context naturally.
 
 Example:
 
 ```bash
-shellbrain recall --json '{"query":"What architectural constraints matter before moving this CLI handler?","current_problem":{"goal":"move CLI handler without breaking clean architecture","surface":"entrypoints, startup, and handler dependency wiring","obstacle":"handler currently imports startup types","hypothesis":"startup should construct dependencies but handler should receive protocols"}}'
+shellbrain recall "What architectural constraints matter before moving this CLI handler?"
 ```
 
 ## Query Guidance
@@ -114,19 +109,19 @@ Good recall queries are concrete. Name the failure mode, subsystem, decision, fi
 Prior attempt query:
 
 ```bash
-shellbrain recall --json '{"query":"Have we seen this migration lock timeout before?","current_problem":{"goal":"fix migration test failure","surface":"database migrations and schema setup","obstacle":"migration blocks waiting on lock","hypothesis":"a previous test leaves a transaction open"}}'
+shellbrain recall "I'm debugging a migration lock timeout. What prior context matters?"
 ```
 
 Constraint query:
 
 ```bash
-shellbrain recall --json '{"query":"What repo constraints or user preferences matter for this auth refactor?","current_problem":{"goal":"refactor auth callback handling","surface":"auth routes and callback tests","obstacle":"unclear existing conventions for redirect behavior","hypothesis":"there is a repo-specific callback invariant"}}'
+shellbrain recall "What repo constraints or user preferences matter for this auth callback refactor?"
 ```
 
 Area-specific query:
 
 ```bash
-shellbrain recall --json '{"query":"What facts or recent changes matter around the payments retry worker?","current_problem":{"goal":"debug retry worker failure","surface":"payments retry worker","obstacle":"retry state diverges after timeout","hypothesis":"recent retry policy change affected idempotency"}}'
+shellbrain recall "What facts or recent changes matter around the payments retry worker timeout?"
 ```
 
 Avoid generic prompts like: