shellbrain 0.1.35__tar.gz → 0.1.37__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.35
+Version: 0.1.37
 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.
 
 ---
@@ -36,7 +57,7 @@ Episodic, empirical, conceptual. Three categories, one retrieval surface.
 - An ontology of problems, solutions, failed tactics, facts, preferences, changes.
 - This is **case-based reasoning** in a semantic graph.
 
-**Conceptual konwledge** is the _abstractive_ layer.
+**Conceptual knowledge** is the _abstractive_ layer.
 - A **higher-level concept graph** with claims, relations, and implementations that link back to the concrete layer.
 - **Progressive disclosure.** agents get oriented first, then ask for depth only where tasks require it.
 
@@ -44,21 +65,52 @@ 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"}}'
+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"}}'
 ```
 
-Lower-level commands exist for inner agents.
-- `read`, `events`, `concept show`, `memory add`, `memory update`, `concept add`, `concept update`
-
-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.
+Response shape:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "brief": {
+      "summary": "...",
+      "constraints": ["..."],
+      "known_traps": ["..."],
+      "prior_cases": ["..."],
+      "concept_orientation": ["..."],
+      "anchors": ["`README.md`"],
+      "conflicts": ["..."],
+      "gaps": ["..."],
+      "next_checks": ["..."],
+      "sources": [
+        {
+          "kind": "memory",
+          "id": "...",
+          "section": "direct"
+        }
+      ]
+    },
+    "fallback_reason": null
+  },
+  "errors": []
+}
+```
 
 **Working agents focus on only their work.**
 
+### Teach
+
+**Working agents call `shellbrain teach` for explicit teaching.** You can tell an agent to remember important ideas.
+
 ---
 
 ## Principled and Disciplined
@@ -69,27 +121,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 +135,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.
 
 ---
 
@@ -112,8 +143,4 @@ Use Shellbrain in your agent of choice. Then, just work normally.
 
 - [shellbrain.ai/humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
 - [shellbrain.ai/agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
-- [shellbrain.ai/recall](https://shellbrain.ai/recall/) — retrieval pipeline
-- [shellbrain.ai/memory/episodic](https://shellbrain.ai/memory/episodic/) — transcript evidence
-- [shellbrain.ai/memory/semantic](https://shellbrain.ai/memory/semantic/) — facts, preferences, changes
-- [shellbrain.ai/memory/procedural](https://shellbrain.ai/memory/procedural/) — problems, solutions, failed tactics
-- [shellbrain.ai/memory/associative](https://shellbrain.ai/memory/associative/) — explicit links and semantic neighbors
+- [shellbrain.ai/architecture](https://shellbrain.ai/architecture/) — memory model, storage, and boundaries

{shellbrain-0.1.35 → shellbrain-0.1.37}/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.
 
 ---
@@ -22,7 +43,7 @@ Episodic, empirical, conceptual. Three categories, one retrieval surface.
 - An ontology of problems, solutions, failed tactics, facts, preferences, changes.
 - This is **case-based reasoning** in a semantic graph.
 
-**Conceptual konwledge** is the _abstractive_ layer.
+**Conceptual knowledge** is the _abstractive_ layer.
 - A **higher-level concept graph** with claims, relations, and implementations that link back to the concrete layer.
 - **Progressive disclosure.** agents get oriented first, then ask for depth only where tasks require it.
 
@@ -30,21 +51,52 @@ 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"}}'
+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"}}'
 ```
 
-Lower-level commands exist for inner agents.
-- `read`, `events`, `concept show`, `memory add`, `memory update`, `concept add`, `concept update`
-
-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.
+Response shape:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "brief": {
+      "summary": "...",
+      "constraints": ["..."],
+      "known_traps": ["..."],
+      "prior_cases": ["..."],
+      "concept_orientation": ["..."],
+      "anchors": ["`README.md`"],
+      "conflicts": ["..."],
+      "gaps": ["..."],
+      "next_checks": ["..."],
+      "sources": [
+        {
+          "kind": "memory",
+          "id": "...",
+          "section": "direct"
+        }
+      ]
+    },
+    "fallback_reason": null
+  },
+  "errors": []
+}
+```
 
 **Working agents focus on only their work.**
 
+### Teach
+
+**Working agents call `shellbrain teach` for explicit teaching.** You can tell an agent to remember important ideas.
+
 ---
 
 ## Principled and Disciplined
@@ -55,27 +107,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 +121,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.
 
 ---
 
@@ -98,8 +129,4 @@ Use Shellbrain in your agent of choice. Then, just work normally.
 
 - [shellbrain.ai/humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
 - [shellbrain.ai/agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
-- [shellbrain.ai/recall](https://shellbrain.ai/recall/) — retrieval pipeline
-- [shellbrain.ai/memory/episodic](https://shellbrain.ai/memory/episodic/) — transcript evidence
-- [shellbrain.ai/memory/semantic](https://shellbrain.ai/memory/semantic/) — facts, preferences, changes
-- [shellbrain.ai/memory/procedural](https://shellbrain.ai/memory/procedural/) — problems, solutions, failed tactics
-- [shellbrain.ai/memory/associative](https://shellbrain.ai/memory/associative/) — explicit links and semantic neighbors
+- [shellbrain.ai/architecture](https://shellbrain.ai/architecture/) — memory model, storage, and boundaries

{shellbrain-0.1.35 → shellbrain-0.1.37}/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.37}/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.37/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)