shellbrain 0.1.52__tar.gz → 0.1.53__tar.gz

shellbrain-0.1.53/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: shellbrain
+Version: 0.1.53
+Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: SQLAlchemy<3.0,>=2.0
+Requires-Dist: alembic<2.0,>=1.13
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: PyYAML<7.0,>=6.0
+Requires-Dist: psycopg[binary]<4.0,>=3.1
+Requires-Dist: pgvector<1.0,>=0.3
+Requires-Dist: sentence-transformers<4.0,>=3.0
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/cucupac/shellbrain/main/docs/assets/shellbrain_logo_badge.png" alt="ShellBrain logo" height="88">
+</p>
+
+<h3 align="center">ShellBrain</h3>
+
+<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.
+
+## Install
+
+```bash
+curl -L shellbrain.ai/install | bash
+```
+
+**Works for Codex, Claude Code, and Cursor.**
+
+Requirements.
+- macOS or Linux, Python 3.11+, Docker for the managed local Postgres+pgvector runtime.
+
+### Upgrade for latest capabilities
+
+```bash
+shellbrain upgrade
+```
+---
+
+## Recall in one command
+
+<p align="center">
+  <img src="docs/assets/shellbrain-recall-context-diagram.png" alt="ShellBrain recall uses vector search and BM25 to search your memories. An inner recall agent summarizes the search results." width="720">
+</p>
+
+---
+
+## Architecture
+
+ShellBrain builds memory in three grounded layers:
+
+- **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.
+
+---
+
+## How Agents Use ShellBrain
+
+### Recall
+
+Working agents run `shellbrain recall` to get one compact brief for the current task.
+
+Recall receives only the quoted query. Include the relevant task, failure, subsystem, or decision in the question.
+
+```bash
+shellbrain recall "What is ShellBrain, and how does it help a working coding agent?"
+```
+
+**Response format:**
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "brief": {
+      "summary": "...",
+      "constraints": ["..."],
+      "known_traps": ["..."],
+      "prior_cases": ["..."],
+      "concept_orientation": ["..."],
+      "anchors": ["`README.md`"],
+      "conflicts": ["..."],
+      "gaps": ["..."],
+      "next_checks": ["..."]
+    },
+    "fallback_reason": null
+  },
+  "errors": []
+}
+```
+
+The brief lets the working agent focus on the current task.
+
+### Teach
+
+Run `shellbrain teach` only when you explicitly want ShellBrain to remember something important.
+
+---
+
+## Memory Discipline
+
+ShellBrain keeps memory grounded in evidence and narrow in scope. Agents request memory when they need it.
+
+**Memory that cannot justify itself should not persist.**
+
+---
+
+## Use ShellBrain
+
+Use ShellBrain with your preferred agent. Then work as usual.
+
+- **Claude Code:** Use `/shellbrain` to recall context at task boundaries.
+- **Codex:** Use `$shellbrain` to recall context at task boundaries.
+- **Cursor:** Use `/shellbrain` to recall context at task boundaries.
+
+---
+
+## Repair
+
+Run `shellbrain admin doctor` to inspect the installation. If it reports a problem, run `shellbrain init`. Do not run init every session.
+
+---
+
+## Docs
+
+- [For Humans](https://shellbrain.ai/humans/): installation, upgrades, and first steps
+- [For Agents](https://shellbrain.ai/agents/): agent workflow and memory rules
+- [Technical Docs](https://deepwiki.com/cucupac/shellbrain): detailed documentation and code map

shellbrain-0.1.53/README.md

@@ -0,0 +1,120 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/cucupac/shellbrain/main/docs/assets/shellbrain_logo_badge.png" alt="ShellBrain logo" height="88">
+</p>
+
+<h3 align="center">ShellBrain</h3>
+
+<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.
+
+## Install
+
+```bash
+curl -L shellbrain.ai/install | bash
+```
+
+**Works for Codex, Claude Code, and Cursor.**
+
+Requirements.
+- macOS or Linux, Python 3.11+, Docker for the managed local Postgres+pgvector runtime.
+
+### Upgrade for latest capabilities
+
+```bash
+shellbrain upgrade
+```
+---
+
+## Recall in one command
+
+<p align="center">
+  <img src="docs/assets/shellbrain-recall-context-diagram.png" alt="ShellBrain recall uses vector search and BM25 to search your memories. An inner recall agent summarizes the search results." width="720">
+</p>
+
+---
+
+## Architecture
+
+ShellBrain builds memory in three grounded layers:
+
+- **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.
+
+---
+
+## How Agents Use ShellBrain
+
+### Recall
+
+Working agents run `shellbrain recall` to get one compact brief for the current task.
+
+Recall receives only the quoted query. Include the relevant task, failure, subsystem, or decision in the question.
+
+```bash
+shellbrain recall "What is ShellBrain, and how does it help a working coding agent?"
+```
+
+**Response format:**
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "brief": {
+      "summary": "...",
+      "constraints": ["..."],
+      "known_traps": ["..."],
+      "prior_cases": ["..."],
+      "concept_orientation": ["..."],
+      "anchors": ["`README.md`"],
+      "conflicts": ["..."],
+      "gaps": ["..."],
+      "next_checks": ["..."]
+    },
+    "fallback_reason": null
+  },
+  "errors": []
+}
+```
+
+The brief lets the working agent focus on the current task.
+
+### Teach
+
+Run `shellbrain teach` only when you explicitly want ShellBrain to remember something important.
+
+---
+
+## Memory Discipline
+
+ShellBrain keeps memory grounded in evidence and narrow in scope. Agents request memory when they need it.
+
+**Memory that cannot justify itself should not persist.**
+
+---
+
+## Use ShellBrain
+
+Use ShellBrain with your preferred agent. Then work as usual.
+
+- **Claude Code:** Use `/shellbrain` to recall context at task boundaries.
+- **Codex:** Use `$shellbrain` to recall context at task boundaries.
+- **Cursor:** Use `/shellbrain` to recall context at task boundaries.
+
+---
+
+## Repair
+
+Run `shellbrain admin doctor` to inspect the installation. If it reports a problem, run `shellbrain init`. Do not run init every session.
+
+---
+
+## Docs
+
+- [For Humans](https://shellbrain.ai/humans/): installation, upgrades, and first steps
+- [For Agents](https://shellbrain.ai/agents/): agent workflow and memory rules
+- [Technical Docs](https://deepwiki.com/cucupac/shellbrain): detailed documentation and code map

{shellbrain-0.1.52 → shellbrain-0.1.53}/app/core/use_cases/retrieval/build_context/execute.py

@@ -34,7 +34,7 @@ _DEFAULT_SETTINGS = InnerAgentSettings(
     reasoning="medium",
     timeout_seconds=90,
     max_private_reads=0,
-    max_brief_tokens=1_800,
+    max_brief_tokens=500,
 )
 
 

{shellbrain-0.1.52 → shellbrain-0.1.53}/app/infrastructure/host_apps/inner_agents/prompt.py

@@ -291,6 +291,11 @@ Leave a section empty when it has no useful content.
 Summary: max two sentences. Lists: max three items. Items: max one sentence.
 Keep visible anchors minimal because full provenance belongs in telemetry.
 
+# OUTPUT BUDGET
+Treat `max_brief_tokens` as the limit for the complete brief.
+Keep every relevant constraint, trap, conflict, and warning before background context.
+Do not fill the budget when a shorter brief is useful.
+
 # OUTPUT
 Return only valid JSON matching `output_contract`. Return a `brief` object only.
 Keep each list compact.

{shellbrain-0.1.52 → shellbrain-0.1.53}/app/settings/internal-agents/defaults.yaml

@@ -6,7 +6,7 @@ build_context:
   reasoning: low
   timeout_seconds: 90
   max_private_reads: 3
-  max_brief_tokens: 1800
+  max_brief_tokens: 500
 
 build_knowledge:
   provider: auto

{shellbrain-0.1.52 → shellbrain-0.1.53}/pyproject.toml

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

shellbrain-0.1.53/shellbrain.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: shellbrain
+Version: 0.1.53
+Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: SQLAlchemy<3.0,>=2.0
+Requires-Dist: alembic<2.0,>=1.13
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: PyYAML<7.0,>=6.0
+Requires-Dist: psycopg[binary]<4.0,>=3.1
+Requires-Dist: pgvector<1.0,>=0.3
+Requires-Dist: sentence-transformers<4.0,>=3.0
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/cucupac/shellbrain/main/docs/assets/shellbrain_logo_badge.png" alt="ShellBrain logo" height="88">
+</p>
+
+<h3 align="center">ShellBrain</h3>
+
+<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.
+
+## Install
+
+```bash
+curl -L shellbrain.ai/install | bash
+```
+
+**Works for Codex, Claude Code, and Cursor.**
+
+Requirements.
+- macOS or Linux, Python 3.11+, Docker for the managed local Postgres+pgvector runtime.
+
+### Upgrade for latest capabilities
+
+```bash
+shellbrain upgrade
+```
+---
+
+## Recall in one command
+
+<p align="center">
+  <img src="docs/assets/shellbrain-recall-context-diagram.png" alt="ShellBrain recall uses vector search and BM25 to search your memories. An inner recall agent summarizes the search results." width="720">
+</p>
+
+---
+
+## Architecture
+
+ShellBrain builds memory in three grounded layers:
+
+- **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.
+
+---
+
+## How Agents Use ShellBrain
+
+### Recall
+
+Working agents run `shellbrain recall` to get one compact brief for the current task.
+
+Recall receives only the quoted query. Include the relevant task, failure, subsystem, or decision in the question.
+
+```bash
+shellbrain recall "What is ShellBrain, and how does it help a working coding agent?"
+```
+
+**Response format:**
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "brief": {
+      "summary": "...",
+      "constraints": ["..."],
+      "known_traps": ["..."],
+      "prior_cases": ["..."],
+      "concept_orientation": ["..."],
+      "anchors": ["`README.md`"],
+      "conflicts": ["..."],
+      "gaps": ["..."],
+      "next_checks": ["..."]
+    },
+    "fallback_reason": null
+  },
+  "errors": []
+}
+```
+
+The brief lets the working agent focus on the current task.
+
+### Teach
+
+Run `shellbrain teach` only when you explicitly want ShellBrain to remember something important.
+
+---
+
+## Memory Discipline
+
+ShellBrain keeps memory grounded in evidence and narrow in scope. Agents request memory when they need it.
+
+**Memory that cannot justify itself should not persist.**
+
+---
+
+## Use ShellBrain
+
+Use ShellBrain with your preferred agent. Then work as usual.
+
+- **Claude Code:** Use `/shellbrain` to recall context at task boundaries.
+- **Codex:** Use `$shellbrain` to recall context at task boundaries.
+- **Cursor:** Use `/shellbrain` to recall context at task boundaries.
+
+---
+
+## Repair
+
+Run `shellbrain admin doctor` to inspect the installation. If it reports a problem, run `shellbrain init`. Do not run init every session.
+
+---
+
+## Docs
+
+- [For Humans](https://shellbrain.ai/humans/): installation, upgrades, and first steps
+- [For Agents](https://shellbrain.ai/agents/): agent workflow and memory rules
+- [Technical Docs](https://deepwiki.com/cucupac/shellbrain): detailed documentation and code map

shellbrain-0.1.52/PKG-INFO

@@ -1,141 +0,0 @@
-Metadata-Version: 2.4
-Name: shellbrain
-Version: 0.1.52
-Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-Requires-Dist: SQLAlchemy<3.0,>=2.0
-Requires-Dist: alembic<2.0,>=1.13
-Requires-Dist: pydantic<3.0,>=2.7
-Requires-Dist: PyYAML<7.0,>=6.0
-Requires-Dist: psycopg[binary]<4.0,>=3.1
-Requires-Dist: pgvector<1.0,>=0.3
-Requires-Dist: sentence-transformers<4.0,>=3.0
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/cucupac/shellbrain/main/docs/assets/shellbrain_logo_badge.png" alt="ShellBrain logo" height="88">
-</p>
-
-<h3 align="center">ShellBrain</h3>
-
-<p align="center">Long-term Memory for AI Agents.</p>
-
-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.**
-
-## 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.
-
----
-
-## Architecture
-
-**Episodic knowledge** is the _evidence_ layer.
-- What actually happened in the session: your prompts, the agent's steps, tool calls, and outputs.
-
-**Empirical knowledge** is the concrete _extracted_ layer.
-- An ontology of problems, solutions, failed tactics, facts, preferences, changes.
-- This is **case-based reasoning** in a semantic graph.
-
-**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.
-
-The episodic layer is truth. Empirical memory extracts. Concept memory abstracts. **Each layer is grounded in the one beneath it.**
-
----
-
-## How Agents Use ShellBrain
-
-### Recall
-
-**Working agents call `shellbrain recall`.** That is the normal interface they have to think about. One command, **one _carefully curated_ compact brief** for the task at hand.
-
-Recall receives only the quoted query, so include the relevant task, failure, subsystem, or decision naturally in the question.
-
-```bash
-shellbrain recall "What is ShellBrain, and how does it help a working coding agent?"
-```
-
-Response shape:
-
-```json
-{
-  "status": "ok",
-  "data": {
-    "brief": {
-      "summary": "...",
-      "constraints": ["..."],
-      "known_traps": ["..."],
-      "prior_cases": ["..."],
-      "concept_orientation": ["..."],
-      "anchors": ["`README.md`"],
-      "conflicts": ["..."],
-      "gaps": ["..."],
-      "next_checks": ["..."]
-    },
-    "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
-
-Memory that is grounded in evidence, small in scope, and asked for rather than pushed is memory that compounds. Everything else is noise for working agents.
-
-**A memory layer that cannot justify itself should not persist.**
-
----
-
-## How to Use ShellBrain
-
-Use Shellbrain in your agent of choice. Then, just work normally.
-
-**Claude Code:** *Use `/shellbrain` to remember Shellbrain recall at the right task boundaries.*
-
-**Codex:** *Use $shellbrain to remember Shellbrain recall at the right task boundaries.*
-
-**Cursor:** *Use `/shellbrain` to remember Shellbrain recall at the right task boundaries.*
-
----
-
-## Repair
-
-`shellbrain admin doctor` to inspect. `shellbrain init` to repair if doctor flags it. Do not rerun init every session.
-
----
-
-## Docs
-
-- [For Humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
-- [For Agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
-- [Technical Docs](https://deepwiki.com/cucupac/shellbrain) — in-depth generated docs and codebase map

shellbrain-0.1.52/README.md

@@ -1,127 +0,0 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/cucupac/shellbrain/main/docs/assets/shellbrain_logo_badge.png" alt="ShellBrain logo" height="88">
-</p>
-
-<h3 align="center">ShellBrain</h3>
-
-<p align="center">Long-term Memory for AI Agents.</p>
-
-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.**
-
-## 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.
-
----
-
-## Architecture
-
-**Episodic knowledge** is the _evidence_ layer.
-- What actually happened in the session: your prompts, the agent's steps, tool calls, and outputs.
-
-**Empirical knowledge** is the concrete _extracted_ layer.
-- An ontology of problems, solutions, failed tactics, facts, preferences, changes.
-- This is **case-based reasoning** in a semantic graph.
-
-**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.
-
-The episodic layer is truth. Empirical memory extracts. Concept memory abstracts. **Each layer is grounded in the one beneath it.**
-
----
-
-## How Agents Use ShellBrain
-
-### Recall
-
-**Working agents call `shellbrain recall`.** That is the normal interface they have to think about. One command, **one _carefully curated_ compact brief** for the task at hand.
-
-Recall receives only the quoted query, so include the relevant task, failure, subsystem, or decision naturally in the question.
-
-```bash
-shellbrain recall "What is ShellBrain, and how does it help a working coding agent?"
-```
-
-Response shape:
-
-```json
-{
-  "status": "ok",
-  "data": {
-    "brief": {
-      "summary": "...",
-      "constraints": ["..."],
-      "known_traps": ["..."],
-      "prior_cases": ["..."],
-      "concept_orientation": ["..."],
-      "anchors": ["`README.md`"],
-      "conflicts": ["..."],
-      "gaps": ["..."],
-      "next_checks": ["..."]
-    },
-    "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
-
-Memory that is grounded in evidence, small in scope, and asked for rather than pushed is memory that compounds. Everything else is noise for working agents.
-
-**A memory layer that cannot justify itself should not persist.**
-
----
-
-## How to Use ShellBrain
-
-Use Shellbrain in your agent of choice. Then, just work normally.
-
-**Claude Code:** *Use `/shellbrain` to remember Shellbrain recall at the right task boundaries.*
-
-**Codex:** *Use $shellbrain to remember Shellbrain recall at the right task boundaries.*
-
-**Cursor:** *Use `/shellbrain` to remember Shellbrain recall at the right task boundaries.*
-
----
-
-## Repair
-
-`shellbrain admin doctor` to inspect. `shellbrain init` to repair if doctor flags it. Do not rerun init every session.
-
----
-
-## Docs
-
-- [For Humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
-- [For Agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
-- [Technical Docs](https://deepwiki.com/cucupac/shellbrain) — in-depth generated docs and codebase map