shellbrain 0.1.35__tar.gz → 0.1.36__tar.gz

{shellbrain-0.1.35 → shellbrain-0.1.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.35
+Version: 0.1.36
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -22,7 +22,28 @@ Requires-Dist: sentence-transformers<4.0,>=3.0
 
 Agents forget across sessions. They rediscover the same problems, repeat the same mistakes, and relearn what you already taught them. **ShellBrain makes their work compound.**
 
-### Recall in one command.
+## Install
+
+```bash
+curl -L shellbrain.ai/install | bash
+```
+
+**Works for Codex, Claude Code, and Cursor.** The installer runs `shellbrain init` for you. Repos register themselves on first use.
+
+Requirements.
+- macOS or Linux, Python 3.11+, Docker for the managed local Postgres+pgvector runtime.
+
+### Upgrade for latest capabilities
+
+```bash
+shellbrain upgrade
+```
+
+The install script also works as an upgrade path: `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pipx upgrade shellbrain && shellbrain init`.
+
+---
+
+## Recall in one command.
 Episodic, empirical, conceptual. Three categories, one retrieval surface.
 
 ---
@@ -44,20 +65,21 @@ The episodic layer is truth. Empirical memory extracts. Concept memory abstracts
 
 ---
 
-## How agents use ShellBrain
+## How Agents Use ShellBrain
 
-**Working agents call `recall`.** That is the normal interface they have to think about. One command, **one _carefully curated_ compact brief**, with sources cited.
+### Recall
+
+**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.
 
 ```bash
 shellbrain recall --json '{"query":"what context matters for this migration lock timeout?","current_problem":{"goal":"fix the migration hang","surface":"db admin","obstacle":"lock timeout","hypothesis":"none yet"}}'
 ```
 
-Lower-level commands exist for inner agents.
-- `read`, `events`, `concept show`, `memory add`, `memory update`, `concept add`, `concept update`
+**Working agents focus on only their work.**
 
-When a user explicitly says to store or teach Shellbrain something, working agents can call `teach`. It stores the statement as evidence and immediately runs Shellbrain's teach agent.
+### Teach
 
-**Working agents focus on only their work.**
+**Working agents call `shellbrain teach` for explicit teaching.** You can tell an agent to remember important ideas.
 
 ---
 
@@ -69,27 +91,6 @@ Memory that is grounded in evidence, small in scope, and asked for rather than p
 
 ---
 
-## Install
-
-```bash
-curl -L shellbrain.ai/install | bash
-```
-
-**Works for Codex, Claude Code, and Cursor.** The installer runs `shellbrain init` for you. Repos register themselves on first use.
-
-Requirements.
-- macOS or Linux, Python 3.11+, Docker for the managed local Postgres+pgvector runtime.
-
-### Upgrade for latest capabilities
-
-```bash
-shellbrain upgrade
-```
-
-The install script also works as an upgrade path: `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pipx upgrade shellbrain && shellbrain init`.
-
----
-
 ## How to Use ShellBrain
 
 Use Shellbrain in your agent of choice. Then, just work normally.
@@ -104,7 +105,7 @@ Use Shellbrain in your agent of choice. Then, just work normally.
 
 ## Repair
 
-`shellbrain admin doctor` to inspect. `shellbrain init` to repair if doctor flags it. Do not rerun init every session — it is not a no-op.
+`shellbrain admin doctor` to inspect. `shellbrain init` to repair if doctor flags it. Do not rerun init every session.
 
 ---
 

{shellbrain-0.1.35 → shellbrain-0.1.36}/README.md

@@ -8,7 +8,28 @@
 
 Agents forget across sessions. They rediscover the same problems, repeat the same mistakes, and relearn what you already taught them. **ShellBrain makes their work compound.**
 
-### Recall in one command.
+## Install
+
+```bash
+curl -L shellbrain.ai/install | bash
+```
+
+**Works for Codex, Claude Code, and Cursor.** The installer runs `shellbrain init` for you. Repos register themselves on first use.
+
+Requirements.
+- macOS or Linux, Python 3.11+, Docker for the managed local Postgres+pgvector runtime.
+
+### Upgrade for latest capabilities
+
+```bash
+shellbrain upgrade
+```
+
+The install script also works as an upgrade path: `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pipx upgrade shellbrain && shellbrain init`.
+
+---
+
+## Recall in one command.
 Episodic, empirical, conceptual. Three categories, one retrieval surface.
 
 ---
@@ -30,20 +51,21 @@ The episodic layer is truth. Empirical memory extracts. Concept memory abstracts
 
 ---
 
-## How agents use ShellBrain
+## How Agents Use ShellBrain
 
-**Working agents call `recall`.** That is the normal interface they have to think about. One command, **one _carefully curated_ compact brief**, with sources cited.
+### Recall
+
+**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.
 
 ```bash
 shellbrain recall --json '{"query":"what context matters for this migration lock timeout?","current_problem":{"goal":"fix the migration hang","surface":"db admin","obstacle":"lock timeout","hypothesis":"none yet"}}'
 ```
 
-Lower-level commands exist for inner agents.
-- `read`, `events`, `concept show`, `memory add`, `memory update`, `concept add`, `concept update`
+**Working agents focus on only their work.**
 
-When a user explicitly says to store or teach Shellbrain something, working agents can call `teach`. It stores the statement as evidence and immediately runs Shellbrain's teach agent.
+### Teach
 
-**Working agents focus on only their work.**
+**Working agents call `shellbrain teach` for explicit teaching.** You can tell an agent to remember important ideas.
 
 ---
 
@@ -55,27 +77,6 @@ Memory that is grounded in evidence, small in scope, and asked for rather than p
 
 ---
 
-## Install
-
-```bash
-curl -L shellbrain.ai/install | bash
-```
-
-**Works for Codex, Claude Code, and Cursor.** The installer runs `shellbrain init` for you. Repos register themselves on first use.
-
-Requirements.
-- macOS or Linux, Python 3.11+, Docker for the managed local Postgres+pgvector runtime.
-
-### Upgrade for latest capabilities
-
-```bash
-shellbrain upgrade
-```
-
-The install script also works as an upgrade path: `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pipx upgrade shellbrain && shellbrain init`.
-
----
-
 ## How to Use ShellBrain
 
 Use Shellbrain in your agent of choice. Then, just work normally.
@@ -90,7 +91,7 @@ Use Shellbrain in your agent of choice. Then, just work normally.
 
 ## Repair
 
-`shellbrain admin doctor` to inspect. `shellbrain init` to repair if doctor flags it. Do not rerun init every session — it is not a no-op.
+`shellbrain admin doctor` to inspect. `shellbrain init` to repair if doctor flags it. Do not rerun init every session.
 
 ---
 

{shellbrain-0.1.35 → shellbrain-0.1.36}/app/core/entities/associations.py

@@ -18,7 +18,6 @@ class AssociationRelationType(str, Enum):
 
     DEPENDS_ON = "depends_on"
     ASSOCIATED_WITH = "associated_with"
-    MATURES_INTO = "matures_into"
 
 
 class AssociationSourceMode(str, Enum):

{shellbrain-0.1.35 → shellbrain-0.1.36}/app/core/entities/concepts.py

@@ -35,6 +35,16 @@ class ConceptLifecycleStatus(str, Enum):
     STALE = "stale"
     SUPERSEDED = "superseded"
     WRONG = "wrong"
+    ARCHIVED = "archived"
+
+
+class ConceptLifecycleTargetType(str, Enum):
+    """Truth-bearing concept record types with mutable lifecycle state."""
+
+    RELATION = "relation"
+    CLAIM = "claim"
+    GROUNDING = "grounding"
+    MEMORY_LINK = "memory_link"
 
 
 class ConceptRelationPredicate(str, Enum):
@@ -73,7 +83,6 @@ class AnchorKind(str, Enum):
     LOG = "log"
     DOC = "doc"
     COMMIT = "commit"
-    MEMORY = "memory"
 
 
 class AnchorStatus(str, Enum):
@@ -103,10 +112,8 @@ class ConceptMemoryLinkRole(str, Enum):
     EXAMPLE_OF = "example_of"
     SOLUTION_FOR = "solution_for"
     FAILED_TACTIC_FOR = "failed_tactic_for"
-    CHANGED = "changed"
-    VALIDATED = "validated"
-    CONTRADICTED = "contradicted"
-    WARNED_ABOUT = "warned_about"
+    WARNS_ABOUT = "warns_about"
+    CHANGE_RELEVANT_TO = "change_relevant_to"
 
 
 class ConceptEvidenceTargetType(str, Enum):
@@ -116,6 +123,7 @@ class ConceptEvidenceTargetType(str, Enum):
     CLAIM = "claim"
     GROUNDING = "grounding"
     MEMORY_LINK = "memory_link"
+    LIFECYCLE_EVENT = "lifecycle_event"
 
 
 class ConceptEvidenceKind(str, Enum):
@@ -193,10 +201,28 @@ class ConceptLifecycle:
     confidence: float = 0.5
     observed_at: datetime | None = None
     validated_at: datetime | None = None
+    invalidated_at: datetime | None = None
     source_kind: ConceptSourceKind | None = None
     source_ref: str | None = None
     superseded_by_id: str | None = None
     created_by: ConceptCreatedBy = ConceptCreatedBy.MANUAL
+    updated_by: ConceptCreatedBy | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ConceptLifecycleEvent:
+    """One auditable lifecycle transition for a truth-bearing concept record."""
+
+    id: str
+    repo_id: str
+    target_type: ConceptLifecycleTargetType
+    target_id: str
+    from_status: ConceptLifecycleStatus
+    to_status: ConceptLifecycleStatus
+    rationale: str
+    actor: ConceptCreatedBy
+    superseded_by_id: str | None = None
+    created_at: datetime | None = None
 
 
 @dataclass(frozen=True, kw_only=True)

shellbrain-0.1.36/app/core/entities/evidence.py

@@ -0,0 +1,222 @@
+"""This module defines evidence references and unified evidence-link entities."""
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+
+from app.core.entities.ids import (
+    AssociationEdgeId,
+    EvidenceId,
+    EvidenceRefText,
+    MemoryId,
+    RepoId,
+)
+
+
+class EvidenceTargetType(str, Enum):
+    """Storage-neutral targets that may carry evidence."""
+
+    MEMORY = "memory"
+    ASSOCIATION_EDGE = "association_edge"
+    UTILITY_OBSERVATION = "utility_observation"
+    CONCEPT_CLAIM = "concept_claim"
+    CONCEPT_RELATION = "concept_relation"
+    CONCEPT_GROUNDING = "concept_grounding"
+    CONCEPT_MEMORY_LINK = "concept_memory_link"
+    CONCEPT_LIFECYCLE_EVENT = "concept_lifecycle_event"
+    MEMORY_LIFECYCLE_EVENT = "memory_lifecycle_event"
+    STRUCTURAL_MEMORY_RELATION = "structural_memory_relation"
+
+
+class EvidenceSourceKind(str, Enum):
+    """Storage-neutral kinds of evidence sources."""
+
+    EPISODE_EVENT = "episode_event"
+    ANCHOR = "anchor"
+    MEMORY = "memory"
+    COMMIT = "commit"
+    TRANSCRIPT = "transcript"
+    TEST = "test"
+    MANUAL = "manual"
+
+
+class EvidenceRole(str, Enum):
+    """Semantic role an evidence source plays for a target."""
+
+    SUPPORTS = "supports"
+    CONTRADICTS = "contradicts"
+    OBSERVED_IN = "observed_in"
+    CREATED_FROM = "created_from"
+    VALIDATED_BY = "validated_by"
+    INVALIDATED_BY = "invalidated_by"
+    EXPLAINS = "explains"
+
+
+@dataclass(kw_only=True)
+class EvidenceRef:
+    """This dataclass models a canonical evidence reference entry."""
+
+    id: EvidenceId
+    repo_id: RepoId
+    ref: EvidenceRefText
+    kind: EvidenceSourceKind = EvidenceSourceKind.EPISODE_EVENT
+    canonical_hash: str | None = None
+    episode_event_id: str | None = None
+    anchor_id: str | None = None
+    memory_id: str | None = None
+    commit_ref: str | None = None
+    transcript_ref: str | None = None
+    note: str | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class EvidenceTarget:
+    """One evidence-backed target in the unified evidence API."""
+
+    target_type: EvidenceTargetType
+    target_id: str
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "target_type", EvidenceTargetType(self.target_type)
+        )
+        if not self.target_id.strip():
+            raise ValueError("evidence target_id must be non-empty")
+
+
+@dataclass(frozen=True, kw_only=True)
+class EvidenceSource:
+    """One normalized source that can support an evidence-backed target."""
+
+    source_kind: EvidenceSourceKind
+    ref: str | None = None
+    episode_event_id: str | None = None
+    anchor_id: str | None = None
+    memory_id: str | None = None
+    commit_ref: str | None = None
+    transcript_ref: str | None = None
+    note: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "source_kind", EvidenceSourceKind(self.source_kind)
+        )
+        if self.source_kind is EvidenceSourceKind.EPISODE_EVENT:
+            event_ref = self.ref or self.episode_event_id
+            if event_ref is None or not event_ref.strip():
+                raise ValueError("episode_event evidence requires ref")
+            if self.ref is not None and self.episode_event_id is not None:
+                if self.ref != self.episode_event_id:
+                    raise ValueError("episode_event ref and episode_event_id differ")
+            object.__setattr__(self, "ref", event_ref)
+            object.__setattr__(self, "episode_event_id", event_ref)
+            _require_no_fields(
+                self,
+                "anchor_id",
+                "memory_id",
+                "commit_ref",
+                "transcript_ref",
+                "note",
+            )
+            return
+
+        required_field = _SOURCE_REQUIRED_FIELD[self.source_kind]
+        _require_one_field(self, required_field)
+        _require_no_fields(
+            self,
+            *(
+                field
+                for field in _SOURCE_REFERENCE_FIELDS
+                if field != required_field
+            ),
+            "ref",
+            "episode_event_id",
+        )
+
+
+@dataclass(frozen=True, kw_only=True)
+class EvidenceLinkView:
+    """One resolved evidence link with a storage-neutral target and source."""
+
+    target: EvidenceTarget
+    source: EvidenceSource
+    role: EvidenceRole
+    evidence_id: EvidenceId | None = None
+    created_at: datetime | None = None
+
+
+@dataclass(kw_only=True)
+class MemoryEvidenceLink:
+    """This dataclass models a many-to-many link between shellbrain and evidence."""
+
+    memory_id: MemoryId
+    evidence_id: EvidenceId
+
+
+@dataclass(kw_only=True)
+class AssociationEdgeEvidenceLink:
+    """This dataclass models a many-to-many link between association edges and evidence."""
+
+    edge_id: AssociationEdgeId
+    evidence_id: EvidenceId
+
+
+_SOURCE_REQUIRED_FIELD: dict[EvidenceSourceKind, str] = {
+    EvidenceSourceKind.ANCHOR: "anchor_id",
+    EvidenceSourceKind.MEMORY: "memory_id",
+    EvidenceSourceKind.COMMIT: "commit_ref",
+    EvidenceSourceKind.TRANSCRIPT: "transcript_ref",
+    EvidenceSourceKind.TEST: "note",
+    EvidenceSourceKind.MANUAL: "note",
+}
+_SOURCE_REFERENCE_FIELDS = frozenset(_SOURCE_REQUIRED_FIELD.values())
+
+
+def _require_one_field(source: EvidenceSource, field: str) -> None:
+    value = getattr(source, field)
+    if value is None or not str(value).strip():
+        raise ValueError(f"{source.source_kind.value} evidence requires {field}")
+
+
+def _require_no_fields(source: EvidenceSource, *fields: str) -> None:
+    extra_fields = [
+        field
+        for field in fields
+        if getattr(source, field) is not None
+    ]
+    if extra_fields:
+        raise ValueError(
+            f"{source.source_kind.value} evidence does not accept: "
+            + ", ".join(sorted(extra_fields))
+        )
+
+
+def canonical_evidence_hash(source: EvidenceSource) -> str:
+    """Return the source-only canonical hash used to dedupe evidence refs."""
+
+    payload = {
+        "kind": source.source_kind.value,
+        "identity": _source_identity(source),
+    }
+    serialized = json.dumps(
+        payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    )
+    return "sha256:" + hashlib.sha256(serialized.encode("utf-8")).hexdigest()
+
+
+def evidence_source_ref(source: EvidenceSource) -> str:
+    """Return the required display/source reference string for one evidence source."""
+
+    return _source_identity(source)
+
+
+def _source_identity(source: EvidenceSource) -> str:
+    if source.source_kind is EvidenceSourceKind.EPISODE_EVENT:
+        assert source.episode_event_id is not None
+        return source.episode_event_id
+    required_field = _SOURCE_REQUIRED_FIELD[source.source_kind]
+    value = getattr(source, required_field)
+    assert value is not None
+    return str(value)

{shellbrain-0.1.35 → shellbrain-0.1.36}/app/core/entities/memories.py

@@ -9,9 +9,13 @@ from app.core.entities.ids import MemoryId, RepoId
 
 
 MemoryKindValue = Literal[
-    "problem", "solution", "failed_tactic", "fact", "preference", "change", "frontier"
+    "problem", "solution", "failed_tactic", "fact", "preference", "change"
 ]
-AssociationRelationValue = Literal["depends_on", "associated_with", "matures_into"]
+AssociationRelationValue = Literal["depends_on", "associated_with"]
+MemoryLifecycleStatusValue = Literal[
+    "active", "maybe_stale", "stale", "superseded", "wrong", "archived"
+]
+MemoryLifecycleActorValue = Literal["worker", "librarian", "manual", "import"]
 
 
 class MemoryKind(str, Enum):
@@ -23,7 +27,6 @@ class MemoryKind(str, Enum):
     FACT = "fact"
     PREFERENCE = "preference"
     CHANGE = "change"
-    FRONTIER = "frontier"
 
     @property
     def requires_problem_link(self) -> bool:
@@ -65,6 +68,55 @@ class MemoryScope(str, Enum):
     GLOBAL = "global"
 
 
+class MemoryLifecycleStatus(str, Enum):
+    """Lifecycle state for concrete durable memories."""
+
+    ACTIVE = "active"
+    MAYBE_STALE = "maybe_stale"
+    STALE = "stale"
+    SUPERSEDED = "superseded"
+    WRONG = "wrong"
+    ARCHIVED = "archived"
+
+    @property
+    def has_positive_retrieval_signal(self) -> bool:
+        """Return whether normal read/recall may retrieve this memory."""
+
+        return self in DEFAULT_RETRIEVABLE_MEMORY_STATUSES
+
+    @property
+    def retrieval_multiplier(self) -> float:
+        """Return the default retrieval strength multiplier for this lifecycle state."""
+
+        return {
+            MemoryLifecycleStatus.ACTIVE: 1.0,
+            MemoryLifecycleStatus.MAYBE_STALE: 0.65,
+            MemoryLifecycleStatus.STALE: 0.25,
+            MemoryLifecycleStatus.SUPERSEDED: 0.0,
+            MemoryLifecycleStatus.WRONG: 0.0,
+            MemoryLifecycleStatus.ARCHIVED: 0.0,
+        }[self]
+
+
+class MemoryLifecycleActor(str, Enum):
+    """Actor classes allowed to mutate concrete memory lifecycle state."""
+
+    WORKER = "worker"
+    LIBRARIAN = "librarian"
+    MANUAL = "manual"
+    IMPORT = "import"
+
+
+DEFAULT_RETRIEVABLE_MEMORY_STATUSES: Final[tuple[MemoryLifecycleStatus, ...]] = (
+    MemoryLifecycleStatus.ACTIVE,
+    MemoryLifecycleStatus.MAYBE_STALE,
+    MemoryLifecycleStatus.STALE,
+)
+DEFAULT_RETRIEVABLE_MEMORY_STATUS_VALUES: Final[tuple[str, ...]] = tuple(
+    status.value for status in DEFAULT_RETRIEVABLE_MEMORY_STATUSES
+)
+
+
 @dataclass(frozen=True)
 class EvidenceRefs:
     """Validated immutable episode-event evidence references."""
@@ -138,9 +190,33 @@ class Memory:
     kind: MemoryKind
     text: str
     created_at: datetime | None = None
-    archived: bool = False
+    status: MemoryLifecycleStatus = MemoryLifecycleStatus.ACTIVE
+    validated_at: datetime | None = None
+    invalidated_at: datetime | None = None
+    superseded_by_id: MemoryId | None = None
+    updated_by: MemoryLifecycleActor | None = None
 
     def is_visible_in(self, repo_id: RepoId | str) -> bool:
         """Return whether this memory is visible inside a repo operation context."""
 
         return self.repo_id == repo_id or self.scope == MemoryScope.GLOBAL
+
+    def has_positive_retrieval_signal(self) -> bool:
+        """Return whether normal read/recall should retrieve this memory."""
+
+        return self.status.has_positive_retrieval_signal
+
+
+@dataclass(kw_only=True)
+class MemoryLifecycleEvent:
+    """Append-only audit event for concrete memory lifecycle transitions."""
+
+    id: str
+    repo_id: RepoId
+    memory_id: MemoryId
+    from_status: MemoryLifecycleStatus
+    to_status: MemoryLifecycleStatus
+    rationale: str
+    actor: MemoryLifecycleActor
+    superseded_by_id: MemoryId | None = None
+    created_at: datetime | None = None