shellbrain 0.1.57__tar.gz → 0.1.58__tar.gz

{shellbrain-0.1.57 → shellbrain-0.1.58}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.57
+Version: 0.1.58
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -20,7 +20,7 @@ Requires-Dist: sentence-transformers<4.0,>=3.0
 
 <p align="center">Long-term Memory for AI Agents.</p>
 
-ShellBrain gives AI agents memory, so they can store and reuse what they learn over time.
+ShellBrain carries useful lessons from one agent task to the next. It preserves decision reasons, failed approaches, product direction, and preferences that the resulting code does not explain.
 
 ## Install
 
@@ -53,13 +53,13 @@ You can also run `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pi
 
 ## Architecture
 
-ShellBrain builds memory in three grounded layers:
+ShellBrain stores evidence and two forms of reusable knowledge:
 
 - **Episodic knowledge records evidence.** It stores prompts, agent steps, tool calls, and outputs from each session.
 - **Empirical knowledge extracts concrete memories.** It organizes problems, solutions, failed tactics, facts, preferences, and changes in a semantic graph for **case-based reasoning**.
 - **Conceptual knowledge abstracts reusable ideas.** Its concept graph connects claims, relations, and implementations to empirical knowledge.
 
-Each higher layer links to evidence in the layer below it. Agents receive a compact orientation first, then request more detail when needed.
+Memories and concept claims link to supporting evidence. A concept can express a product principle without a duplicate memory. Current code remains the source of truth for implementation details.
 
 ---
 
@@ -98,7 +98,7 @@ shellbrain recall "What is ShellBrain, and how does it help a working coding age
 }
 ```
 
-The brief lets the working agent focus on the current task.
+Recall selects an evidence pack in code, then asks an inner agent to summarize it. Source attribution comes from the selected records. Fast mode and provider failures return a brief directly from that same pack.
 
 ### Teach
 

{shellbrain-0.1.57 → shellbrain-0.1.58}/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">Long-term Memory for AI Agents.</p>
 
-ShellBrain gives AI agents memory, so they can store and reuse what they learn over time.
+ShellBrain carries useful lessons from one agent task to the next. It preserves decision reasons, failed approaches, product direction, and preferences that the resulting code does not explain.
 
 ## Install
 
@@ -39,13 +39,13 @@ You can also run `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pi
 
 ## Architecture
 
-ShellBrain builds memory in three grounded layers:
+ShellBrain stores evidence and two forms of reusable knowledge:
 
 - **Episodic knowledge records evidence.** It stores prompts, agent steps, tool calls, and outputs from each session.
 - **Empirical knowledge extracts concrete memories.** It organizes problems, solutions, failed tactics, facts, preferences, and changes in a semantic graph for **case-based reasoning**.
 - **Conceptual knowledge abstracts reusable ideas.** Its concept graph connects claims, relations, and implementations to empirical knowledge.
 
-Each higher layer links to evidence in the layer below it. Agents receive a compact orientation first, then request more detail when needed.
+Memories and concept claims link to supporting evidence. A concept can express a product principle without a duplicate memory. Current code remains the source of truth for implementation details.
 
 ---
 
@@ -84,7 +84,7 @@ shellbrain recall "What is ShellBrain, and how does it help a working coding age
 }
 ```
 
-The brief lets the working agent focus on the current task.
+Recall selects an evidence pack in code, then asks an inner agent to summarize it. Source attribution comes from the selected records. Fast mode and provider failures return a brief directly from that same pack.
 
 ### Teach
 

{shellbrain-0.1.57 → shellbrain-0.1.58}/app/core/entities/inner_agents.py

@@ -15,7 +15,7 @@ InnerAgentName = Literal["build_context", "build_knowledge", "teach"]
 InnerAgentProviderName = str
 InnerAgentReasoningLevel = Literal["none", "minimal", "low", "medium", "high", "xhigh"]
 BuildContextStrategy = Literal[
-    "deterministic_synthesis", "deterministic_only", "autonomous"
+    "deterministic_synthesis", "deterministic_only"
 ]
 TokenCaptureQuality = Literal["exact", "estimated"]
 InnerAgentRunStatus = Literal[
@@ -36,7 +36,6 @@ class BuildContextSettings(_StrictModel):
     model: str = Field(min_length=1)
     reasoning: InnerAgentReasoningLevel
     timeout_seconds: int = Field(ge=1, le=600)
-    max_private_reads: int = Field(default=0, ge=0, le=10)
     max_brief_tokens: int | None = Field(default=None, ge=1, le=100_000)
 
 

{shellbrain-0.1.57 → shellbrain-0.1.58}/app/core/entities/settings.py

@@ -89,28 +89,8 @@ class ReadPolicySettings:
         }
 
 
-@dataclass(frozen=True)
-class CreatePolicySettings:
-    """Create-policy validation and hydration settings."""
-
-    gates: tuple[str, ...]
-    defaults: Mapping[str, Any]
-
-    def hydration_defaults(self) -> dict[str, Any]:
-        return dict(self.defaults)
-
-    def to_dict(self) -> dict[str, Any]:
-        return {"gates": list(self.gates), "defaults": dict(self.defaults)}
-
 
-@dataclass(frozen=True)
-class UpdatePolicySettings:
-    """Update-policy validation settings."""
 
-    gates: tuple[str, ...]
-
-    def to_dict(self) -> dict[str, Any]:
-        return {"gates": list(self.gates)}
 
 
 @dataclass(frozen=True)

{shellbrain-0.1.57 → shellbrain-0.1.58}/app/core/policies/retrieval/ontology_semantics.py

@@ -24,15 +24,6 @@ LIFECYCLE_RETRIEVAL_MULTIPLIERS: Mapping[str, float] = {
     status.value: status.retrieval_multiplier for status in MemoryLifecycleStatus
 }
 
-BUNDLE_FRESHNESS_MULTIPLIERS: Mapping[str, float] = {
-    ACTIVE_STATUS: 1.0,
-    MAYBE_STALE_STATUS: 0.75,
-    STALE_STATUS: 0.45,
-    SUPERSEDED_STATUS: 0.0,
-    WRONG_STATUS: 0.0,
-    ARCHIVED_STATUS: 0.0,
-}
-
 CONCEPT_MEMORY_HIGH_SIGNAL_ROLES = frozenset(
     {
         "solution_for",
@@ -52,13 +43,6 @@ STRUCTURAL_FACT_UPDATE_RELATION_PREDICATES = (
 
 REVERSIBLE_ASSOCIATION_RELATION_TYPES = frozenset({"associated_with"})
 
-_STATUS_PRECEDENCE = (
-    WRONG_STATUS,
-    ARCHIVED_STATUS,
-    SUPERSEDED_STATUS,
-    STALE_STATUS,
-    MAYBE_STALE_STATUS,
-)
 _STRUCTURAL_EXPANSION_BY_PREDICATE = {
     "solved_by": "problem_attempt",
     "failed_with": "problem_attempt",
@@ -85,6 +69,8 @@ def lifecycle_retrieval_multiplier(status: Any) -> float:
     """Return the default positive retrieval multiplier for one lifecycle status."""
 
     return LIFECYCLE_RETRIEVAL_MULTIPLIERS[normalize_lifecycle_status(status)]
+
+
 def is_active_lifecycle(status: Any) -> bool:
     """Return whether a lifecycle status is active."""
 
@@ -109,22 +95,6 @@ def lifecycle_status_counts(statuses: Iterable[Any]) -> dict[str, int]:
     }
 
 
-def dominant_lifecycle_status(statuses: Iterable[Any]) -> str:
-    """Return the status that should dominate currentness interpretation."""
-
-    normalized = tuple(normalize_lifecycle_status(status) for status in statuses)
-    for status in _STATUS_PRECEDENCE:
-        if status in normalized:
-            return status
-    return ACTIVE_STATUS
-
-
-def concept_bundle_retrieval_multiplier(statuses: Iterable[Any]) -> float:
-    """Return the freshness multiplier for an aggregate concept bundle."""
-
-    return BUNDLE_FRESHNESS_MULTIPLIERS[dominant_lifecycle_status(statuses)]
-
-
 def bundle_lifecycle_statuses(bundle: Mapping[str, Any]) -> tuple[str, ...]:
     """Return lifecycle status values across every truth-bearing concept facet."""
 
@@ -135,23 +105,6 @@ def bundle_lifecycle_statuses(bundle: Mapping[str, Any]) -> tuple[str, ...]:
     )
 
 
-def aggregate_currentness_payload(
-    statuses: Iterable[Any], *, record_label: str
-) -> dict[str, str]:
-    """Return currentness text for a group of truth-bearing records."""
-
-    status = dominant_lifecycle_status(statuses)
-    if status == ACTIVE_STATUS:
-        return {
-            "currentness": "current",
-            "temporal_reason": f"all included {record_label} are active",
-        }
-    return {
-        "currentness": status,
-        "temporal_reason": f"one or more {record_label} are marked {status}",
-    }
-
-
 def lifecycle_currentness_payload(
     lifecycle: Any, *, active_reason: str, validated_reason: str
 ) -> dict[str, str]:
@@ -211,7 +164,9 @@ def structural_relation_expansion_type(predicate: Any) -> str:
     try:
         return _STRUCTURAL_EXPANSION_BY_PREDICATE[value]
     except KeyError as exc:
-        raise ValueError(f"unsupported structural memory relation predicate: {value}") from exc
+        raise ValueError(
+            f"unsupported structural memory relation predicate: {value}"
+        ) from exc
 
 
 def why_included_for_expansion(expansion_type: str) -> str:

{shellbrain-0.1.57 → shellbrain-0.1.58}/app/core/ports/host_apps/inner_agents.py

@@ -31,12 +31,10 @@ class InnerAgentRunRequest(_StrictModel):
     model: str = Field(min_length=1)
     reasoning: InnerAgentReasoningLevel
     timeout_seconds: int = Field(ge=1, le=600)
-    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)
     repo_root: str | None = None
-    synthesis_only: bool = False
-    deterministic_pack: dict[str, Any] | None = None
+    deterministic_pack: dict[str, Any]
 
 
 class InnerAgentRunResult(_StrictModel):
@@ -61,7 +59,6 @@ class InnerAgentRunResult(_StrictModel):
     concept_expansion_count: int = Field(default=0, ge=0)
     error_code: str | None = None
     error_message: str | None = None
-    read_trace: dict[str, Any] = Field(default_factory=dict)
 
 
 class BuildKnowledgeAgentRequest(_StrictModel):

{shellbrain-0.1.57 → shellbrain-0.1.58}/app/core/use_cases/concepts/show/execute.py

@@ -6,7 +6,7 @@ from app.core.errors import DomainValidationError, ErrorCode, ErrorDetail
 from app.core.ports.db.unit_of_work import IUnitOfWork
 from app.core.use_cases.concepts.show.request import ConceptShowRequest
 from app.core.use_cases.concepts.show.result import ConceptShowResult
-from app.core.use_cases.concepts.views import serialize_concept_bundle
+from app.core.use_cases.concepts.views import serialize_concept_show
 
 
 def show_concept(request: ConceptShowRequest, uow: IUnitOfWork) -> ConceptShowResult:
@@ -27,6 +27,31 @@ def show_concept(request: ConceptShowRequest, uow: IUnitOfWork) -> ConceptShowRe
                 )
             ]
         )
+    include = set(request.include)
+    endpoint_ids = {
+        concept_id
+        for relation in bundle["relations"]
+        if "relations" in include
+        for concept_id in (relation.subject_concept_id, relation.object_concept_id)
+    }
+    memory_ids = {
+        link.memory_id for link in bundle["memory_links"] if "memory_links" in include
+    }
+    related_concepts = (
+        uow.concepts.list_concepts_by_ids(
+            repo_id=request.repo_id, concept_ids=sorted(endpoint_ids)
+        )
+        if endpoint_ids
+        else []
+    )
+    related_memories = (
+        uow.memories.list_by_ids(sorted(memory_ids)) if memory_ids else []
+    )
     return ConceptShowResult(
-        concept=serialize_concept_bundle(bundle, include=set(request.include))
+        concept=serialize_concept_show(
+            bundle,
+            include=include,
+            related_concepts={concept.id: concept for concept in related_concepts},
+            related_memories={memory.id: memory for memory in related_memories},
+        )
     )

{shellbrain-0.1.57 → shellbrain-0.1.58}/app/core/use_cases/concepts/show/request.py

@@ -12,6 +12,7 @@ ConceptShowIncludeValue = Literal[
     "relations",
     "groundings",
     "memory_links",
+    "evidence",
     "lifecycle_events",
     "preview_concept",
 ]

{shellbrain-0.1.57 → shellbrain-0.1.58}/app/core/use_cases/concepts/views.py

@@ -18,6 +18,8 @@ from app.core.entities.concepts import (
     ConceptRelation,
 )
 
+from app.core.entities.memories import Memory
+
 
 def serialize_concept_bundle(
     bundle: dict[str, Any], *, include: set[str]
@@ -61,6 +63,8 @@ def serialize_concept_bundle(
         payload["groundings"] = groundings
     if "memory_links" in include:
         payload["memory_links"] = memory_links
+    if "evidence" in include:
+        payload["evidence"] = _evidence_payloads(bundle)
     if "lifecycle_events" in include:
         payload["lifecycle_events"] = _lifecycle_event_payloads(
             bundle["lifecycle_events"],
@@ -84,6 +88,62 @@ def serialize_concept_bundle(
     return payload
 
 
+def serialize_concept_show(
+    bundle: dict[str, Any],
+    *,
+    include: set[str],
+    related_concepts: dict[str, Concept],
+    related_memories: dict[str, Memory],
+) -> dict[str, Any]:
+    """Add readable relation endpoints and linked memories to requested facets."""
+
+    payload = serialize_concept_bundle(bundle, include=include)
+    for relation in payload.get("relations", []):
+        for side in ("subject", "object"):
+            concept = related_concepts[relation[f"{side}_concept_id"]]
+            relation[side] = {
+                "id": concept.id,
+                "ref": concept.slug,
+                "name": concept.name,
+                "kind": concept.kind.value,
+            }
+    for link in payload.get("memory_links", []):
+        memory = related_memories[link["memory_id"]]
+        link.update(
+            kind=memory.kind.value,
+            text=memory.text,
+            memory_status=memory.status.value,
+            memory_created_at=_iso(memory.created_at),
+        )
+    return payload
+
+
+def _evidence_payloads(bundle: dict[str, Any]) -> list[dict[str, Any]]:
+    return [
+        {
+            "id": evidence.id,
+            "target_type": evidence.target_type.value,
+            "target_id": evidence.target_id,
+            "kind": evidence.evidence_kind.value,
+            "anchor_id": evidence.anchor_id,
+            "memory_id": evidence.memory_id,
+            "commit_ref": evidence.commit_ref,
+            "transcript_ref": evidence.transcript_ref,
+            "note": evidence.note,
+            "created_at": _iso(evidence.created_at),
+        }
+        for evidence in sorted(
+            bundle["evidence"],
+            key=lambda item: (
+                item.target_type.value,
+                item.target_id,
+                item.evidence_kind.value,
+                item.id,
+            ),
+        )
+    ]
+
+
 def _alias_to_payload(alias) -> dict[str, Any]:
     return {
         "alias": alias.alias,
@@ -124,7 +184,7 @@ def _grounding_to_payload(
         "concept_id": grounding.concept_id,
         "role": grounding.role.value,
         "anchor_id": grounding.anchor_id,
-        "anchor": anchors_by_id.get(grounding.anchor_id),
+        "anchor": anchors_by_id[grounding.anchor_id],
         "created_at": _iso(grounding.created_at),
         "updated_at": _iso(grounding.updated_at),
         **_lifecycle_payload(grounding.lifecycle),
@@ -213,9 +273,7 @@ def _lifecycle_event_payloads(
             "actor": event.actor.value,
             "superseded_by_id": event.superseded_by_id,
             "created_at": _iso(event.created_at),
-            "evidence_count": evidence_counts.get(
-                f"lifecycle_event:{event.id}", 0
-            ),
+            "evidence_count": evidence_counts.get(f"lifecycle_event:{event.id}", 0),
         }
         for event in sorted(
             events, key=lambda item: (_iso(item.created_at) or "", item.id)

{shellbrain-0.1.57 → shellbrain-0.1.58}/app/core/use_cases/knowledge_builder/build_knowledge/execute.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from datetime import datetime, timedelta
+from datetime import datetime
 
 from app.core.entities.inner_agents import BuildKnowledgeSettings
 from app.core.entities.knowledge_builder import (
@@ -11,6 +11,7 @@ from app.core.entities.knowledge_builder import (
     KnowledgeBuildRunStatus,
 )
 from app.core.ports.db.unit_of_work import IUnitOfWork
+from app.core.use_cases.knowledge_builder.runs import has_running_build
 from app.core.ports.host_apps.inner_agents import (
     BuildKnowledgeAgentRequest,
     BuildKnowledgeAgentResult,
@@ -79,42 +80,20 @@ def execute_build_knowledge(
                 previous_event_watermark=previous_watermark,
                 error_code="no_new_events",
             )
-        running_runs = uow.knowledge_build_runs.list_running_runs(
+        if has_running_build(
+            uow.knowledge_build_runs,
             repo_id=request.repo_id,
             episode_id=request.episode_id,
-        )
-        fresh_running_run = _fresh_running_run(
-            running_runs=running_runs,
             now=now,
             stale_seconds=settings.running_run_stale_seconds,
-        )
-        if fresh_running_run is not None:
+            error_message="running build_knowledge run exceeded stale timeout",
+        ):
             return _skipped_result(
                 settings=settings,
                 event_watermark=event_watermark,
                 previous_event_watermark=previous_watermark,
                 error_code="build_already_running",
             )
-        for stale_run in running_runs:
-            uow.knowledge_build_runs.complete(
-                run_id=stale_run.id,
-                status=KnowledgeBuildRunStatus.TIMEOUT,
-                write_count=stale_run.write_count,
-                skipped_item_count=stale_run.skipped_item_count,
-                input_tokens=stale_run.input_tokens,
-                output_tokens=stale_run.output_tokens,
-                reasoning_output_tokens=stale_run.reasoning_output_tokens,
-                cached_input_tokens_total=stale_run.cached_input_tokens_total,
-                cache_read_input_tokens=stale_run.cache_read_input_tokens,
-                cache_creation_input_tokens=stale_run.cache_creation_input_tokens,
-                capture_quality=stale_run.capture_quality,
-                run_summary=stale_run.run_summary,
-                error_code="stale_running_run",
-                error_message="running build_knowledge run exceeded stale timeout",
-                read_trace=stale_run.read_trace,
-                code_trace=stale_run.code_trace,
-                finished_at=now,
-            )
 
         if request.baseline_only and previous_watermark is None:
             return _record_baseline_run(
@@ -155,43 +134,29 @@ def execute_build_knowledge(
     with uow_factory() as uow:
         uow.knowledge_build_runs.complete(
             run_id=run_id,
-            status=provider_result.status,
-            write_count=provider_result.write_count,
-            skipped_item_count=provider_result.skipped_item_count,
-            input_tokens=provider_result.input_tokens,
-            output_tokens=provider_result.output_tokens,
-            reasoning_output_tokens=provider_result.reasoning_output_tokens,
-            cached_input_tokens_total=provider_result.cached_input_tokens_total,
-            cache_read_input_tokens=provider_result.cache_read_input_tokens,
-            cache_creation_input_tokens=provider_result.cache_creation_input_tokens,
-            capture_quality=provider_result.capture_quality,
-            run_summary=provider_result.run_summary,
-            error_code=provider_result.error_code,
-            error_message=provider_result.error_message,
-            read_trace=provider_result.read_trace,
-            code_trace=provider_result.code_trace,
+            **provider_result.model_dump(
+                exclude={
+                    "provider",
+                    "model",
+                    "reasoning",
+                    "timeout_seconds",
+                    "duration_ms",
+                }
+            ),
             finished_at=clock.now(),
         )
     return BuildKnowledgeResult(
-        status=provider_result.status,
+        **provider_result.model_dump(
+            exclude={
+                "timeout_seconds",
+                "duration_ms",
+                "read_trace",
+                "code_trace",
+            }
+        ),
         run_id=run_id,
         event_watermark=event_watermark,
         previous_event_watermark=previous_watermark,
-        provider=provider_result.provider,
-        model=provider_result.model,
-        reasoning=provider_result.reasoning,
-        write_count=provider_result.write_count,
-        skipped_item_count=provider_result.skipped_item_count,
-        input_tokens=provider_result.input_tokens,
-        output_tokens=provider_result.output_tokens,
-        reasoning_output_tokens=provider_result.reasoning_output_tokens,
-        cached_input_tokens_total=provider_result.cached_input_tokens_total,
-        cache_read_input_tokens=provider_result.cache_read_input_tokens,
-        cache_creation_input_tokens=provider_result.cache_creation_input_tokens,
-        capture_quality=provider_result.capture_quality,
-        run_summary=provider_result.run_summary,
-        error_code=provider_result.error_code,
-        error_message=provider_result.error_message,
     )
 
 
@@ -247,21 +212,6 @@ def _run_provider(
         )
 
 
-def _fresh_running_run(
-    *,
-    running_runs: tuple[KnowledgeBuildRun, ...],
-    now: datetime,
-    stale_seconds: int,
-) -> KnowledgeBuildRun | None:
-    """Return a fresh running row when any active run is still inside its lease."""
-
-    stale_before = now - timedelta(seconds=stale_seconds)
-    for run in running_runs:
-        if run.started_at is None or run.started_at > stale_before:
-            return run
-    return None
-
-
 def _record_baseline_run(
     *,
     request: BuildKnowledgeRequest,

shellbrain-0.1.58/app/core/use_cases/knowledge_builder/runs.py

@@ -0,0 +1,46 @@
+"""Shared lease handling for teaching and session consolidation."""
+
+from datetime import datetime, timedelta
+
+from app.core.entities.knowledge_builder import KnowledgeBuildRunStatus
+from app.core.ports.db.knowledge_builder import IKnowledgeBuildRunsRepo
+
+
+def has_running_build(
+    repo: IKnowledgeBuildRunsRepo,
+    *,
+    repo_id: str,
+    episode_id: str,
+    now: datetime,
+    stale_seconds: int,
+    error_message: str,
+) -> bool:
+    """Keep fresh runs and finalize expired runs under the caller's episode lock."""
+
+    running_runs = repo.list_running_runs(repo_id=repo_id, episode_id=episode_id)
+    stale_before = now - timedelta(seconds=stale_seconds)
+    if any(
+        run.started_at is None or run.started_at > stale_before for run in running_runs
+    ):
+        return True
+    for stale_run in running_runs:
+        repo.complete(
+            run_id=stale_run.id,
+            status=KnowledgeBuildRunStatus.TIMEOUT,
+            write_count=stale_run.write_count,
+            skipped_item_count=stale_run.skipped_item_count,
+            input_tokens=stale_run.input_tokens,
+            output_tokens=stale_run.output_tokens,
+            reasoning_output_tokens=stale_run.reasoning_output_tokens,
+            cached_input_tokens_total=stale_run.cached_input_tokens_total,
+            cache_read_input_tokens=stale_run.cache_read_input_tokens,
+            cache_creation_input_tokens=stale_run.cache_creation_input_tokens,
+            capture_quality=stale_run.capture_quality,
+            run_summary=stale_run.run_summary,
+            error_code="stale_running_run",
+            error_message=error_message,
+            read_trace=stale_run.read_trace,
+            code_trace=stale_run.code_trace,
+            finished_at=now,
+        )
+    return False