shellbrain 0.1.52__tar.gz → 0.1.54__tar.gz

shellbrain-0.1.54/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: shellbrain
+Version: 0.1.54
+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.** 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
+```
+
+You can also run `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pipx upgrade shellbrain && shellbrain init`.
+
+---
+
+## 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.54/README.md

@@ -0,0 +1,123 @@
+<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.** 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
+```
+
+You can also run `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pipx upgrade shellbrain && shellbrain init`.
+
+---
+
+## 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.54}/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.54}/app/entrypoints/cli/parser/builder.py

@@ -38,7 +38,6 @@ _TOP_LEVEL_HELP = dedent(
         - Bootstrap or repair with `shellbrain init`.
         - Upgrade with `shellbrain upgrade`.
         - Check health with `shellbrain admin doctor`.
-        - Review usage with `shellbrain metrics`.
 
       Working agents:
         - Use `shellbrain recall` for normal task context.
@@ -68,7 +67,6 @@ _TOP_LEVEL_HELP = dedent(
       Humans:
       shellbrain init
       shellbrain upgrade
-      shellbrain metrics
       shellbrain admin doctor
       shellbrain admin migrate
 
@@ -386,15 +384,6 @@ _BACKFILL_TOKEN_USAGE_HELP = dedent(
     """
 )
 
-_METRICS_HELP = dedent(
-    """\
-    Generate lightweight metrics snapshots, write local artifacts, and open one browser dashboard that switches repos with arrow keys.
-
-    Example:
-      shellbrain metrics
-    """
-)
-
 _INSTALL_CLAUDE_HOOK_HELP = dedent(
     """\
     Install or update the repo-local Claude Code SessionStart hook used as an explicit repo-local override.
@@ -499,14 +488,6 @@ def build_parser() -> argparse.ArgumentParser:
         formatter_class=_HelpFormatter,
     )
 
-    subparsers.add_parser(
-        "metrics",
-        help="Browse Shellbrain metrics across repos.",
-        description="Generate local metrics snapshots and open one browser dashboard for all repos.",
-        epilog=_METRICS_HELP,
-        formatter_class=_HelpFormatter,
-    )
-
     read_parser = subparsers.add_parser(
         "read",
         help="Read Shellbrain context without mutating state.",

{shellbrain-0.1.52 → shellbrain-0.1.54}/app/entrypoints/cli/runner.py

@@ -89,15 +89,6 @@ def main(
 
         return run_upgrade_command(run_upgrade_command=runtime.run_upgrade_command)
 
-    if args.command == "metrics":
-        from app.entrypoints.cli.handlers.human.metrics import run_metrics_command
-
-        return run_metrics_command(
-            args,
-            warn_or_fail_on_unsafe_app_role=runtime.warn_or_fail_on_unsafe_app_role,
-            run_metrics_dashboard=runtime.run_metrics_dashboard,
-        )
-
     if args.command == "admin":
         from app.entrypoints.cli.handlers.human.admin import run_admin_command
 

{shellbrain-0.1.52 → shellbrain-0.1.54}/app/entrypoints/cli/runtime.py

@@ -31,5 +31,4 @@ class CliRuntime(Protocol):
     init_success_presenter_context: Callable[[], dict[str, Any]]
     run_upgrade_command: Callable[[], int]
     warn_or_fail_on_unsafe_app_role: Callable[[], None]
-    run_metrics_dashboard: Callable[..., object]
     admin_dependencies: Any

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

@@ -77,7 +77,7 @@ shellbrain --no-sync --repo-root "<repo_root>" concept show --help
 
 Do not run `shellbrain recall`.
 Do not write memories, concepts, scenarios, files, settings, or database data.
-Do not run `admin`, `init`, `upgrade`, or `metrics` commands.
+Do not run `admin`, `init`, or `upgrade` commands.
 
 # PROTOCOL
 1. Read `query`, `repo_root`, and the budgets from the payload.
@@ -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.
@@ -451,7 +456,7 @@ Do not edit files.
 Do not run a formatter that writes files.
 Do not commit or push.
 Do not run `shellbrain recall` or `shellbrain snapshot`.
-Do not run `admin`, `init`, `upgrade`, or `metrics` commands.
+Do not run `admin`, `init`, or `upgrade` commands.
 Do not write directly to the database.
 Do not use `graph_patches`.
 Do not use a write command that this prompt does not list.
@@ -707,7 +712,7 @@ shellbrain --repo-root "<repo_root>" concept update --help
 ```
 
 Forbidden: `shellbrain events`, `shellbrain scenario record`, `shellbrain
-recall`, `shellbrain snapshot`, admin/init/upgrade/metrics, direct DB writes,
+recall`, `shellbrain snapshot`, admin/init/upgrade, direct DB writes,
 editing files, formatters, commits, pushes, and any write command not listed
 above.
 
@@ -859,7 +864,7 @@ def render_build_context_prompt(request: InnerAgentRunRequest) -> str:
             "shellbrain concept add",
             "shellbrain concept update",
             "shellbrain scenario record",
-            "any admin, init, upgrade, metrics, or durable write command",
+            "any admin, init, upgrade, or durable write command",
         ],
         "output_contract": {
             "brief": {

{shellbrain-0.1.52 → shellbrain-0.1.54}/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.54}/app/startup/cli.py

@@ -13,7 +13,6 @@ def build_cli_runtime():
 
     from app.startup import create_policy
     from app.startup import episode_sync_launcher
-    from app.startup import metrics as startup_metrics
     from app.startup import operation_dependencies
     from app.startup import read_policy
     from app.startup import repo_context
@@ -63,7 +62,6 @@ def build_cli_runtime():
         init_success_presenter_context=runtime_admin.init_success_presenter_context,
         run_upgrade_command=run_upgrade_command,
         warn_or_fail_on_unsafe_app_role=warn_or_fail_on_unsafe_app_role,
-        run_metrics_dashboard=startup_metrics.run_metrics_dashboard,
         admin_dependencies=build_admin_command_dependencies(),
     )
 

{shellbrain-0.1.52 → shellbrain-0.1.54}/app/startup/cli_runtime.py

@@ -35,5 +35,4 @@ class CliRuntime:
     init_success_presenter_context: Callable[[], dict[str, Any]]
     run_upgrade_command: Callable[[], int]
     warn_or_fail_on_unsafe_app_role: Callable[[], None]
-    run_metrics_dashboard: Callable[..., object]
     admin_dependencies: AdminCommandDependencies

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

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

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

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: shellbrain
+Version: 0.1.54
+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.** 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
+```
+
+You can also run `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pipx upgrade shellbrain && shellbrain init`.
+
+---
+
+## 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.54}/shellbrain.egg-info/SOURCES.txt

@@ -63,8 +63,6 @@ app/core/ports/host_apps/inner_agents.py
 app/core/ports/local_state/__init__.py
 app/core/ports/local_state/session_state_store.py
 app/core/ports/local_state/shadow_git.py
-app/core/ports/reporting/__init__.py
-app/core/ports/reporting/metrics.py
 app/core/ports/system/__init__.py
 app/core/ports/system/clock.py
 app/core/ports/system/idgen.py
@@ -130,8 +128,6 @@ app/core/use_cases/memories/update/request.py
 app/core/use_cases/memories/update/result.py
 app/core/use_cases/metrics/__init__.py
 app/core/use_cases/metrics/analyze_agent_behavior.py
-app/core/use_cases/metrics/build_snapshot.py
-app/core/use_cases/metrics/generate_dashboard.py
 app/core/use_cases/retrieval/__init__.py
 app/core/use_cases/retrieval/concept_seed_retrieval.py
 app/core/use_cases/retrieval/context_pack_pipeline.py
@@ -178,7 +174,6 @@ app/entrypoints/cli/handlers/human/__init__.py
 app/entrypoints/cli/handlers/human/admin.py
 app/entrypoints/cli/handlers/human/admin_dependencies.py
 app/entrypoints/cli/handlers/human/init.py
-app/entrypoints/cli/handlers/human/metrics.py
 app/entrypoints/cli/handlers/human/upgrade.py
 app/entrypoints/cli/handlers/internal_agent/__init__.py
 app/entrypoints/cli/handlers/internal_agent/concepts/__init__.py
@@ -207,7 +202,6 @@ app/entrypoints/cli/parser/builder.py
 app/entrypoints/cli/presenters/__init__.py
 app/entrypoints/cli/presenters/init.py
 app/entrypoints/cli/presenters/json.py
-app/entrypoints/cli/presenters/metrics.py
 app/entrypoints/cli/request_parsing/__init__.py
 app/entrypoints/cli/request_parsing/concepts.py
 app/entrypoints/cli/request_parsing/episodes.py
@@ -265,8 +259,6 @@ app/infrastructure/db/runtime/models/views.py
 app/infrastructure/db/runtime/queries/__init__.py
 app/infrastructure/db/runtime/queries/agent_behavior.py
 app/infrastructure/db/runtime/queries/analytics.py
-app/infrastructure/db/runtime/queries/metrics.py
-app/infrastructure/db/runtime/queries/metrics_adapter.py
 app/infrastructure/db/runtime/queries/model_usage_backfill.py
 app/infrastructure/db/runtime/repos/__init__.py
 app/infrastructure/db/runtime/repos/relational/__init__.py
@@ -340,12 +332,6 @@ app/infrastructure/process/episode_sync/launcher.py
 app/infrastructure/process/episode_sync/lock_file.py
 app/infrastructure/process/episode_sync/poller.py
 app/infrastructure/process/episode_sync/status_store.py
-app/infrastructure/reporting/__init__.py
-app/infrastructure/reporting/metrics/__init__.py
-app/infrastructure/reporting/metrics/artifacts.py
-app/infrastructure/reporting/metrics/browser.py
-app/infrastructure/reporting/metrics/pager.py
-app/infrastructure/reporting/metrics/render_html.py
 app/infrastructure/system/__init__.py
 app/infrastructure/system/clock.py
 app/infrastructure/system/id_generator.py
@@ -389,7 +375,6 @@ app/startup/host_hooks.py
 app/startup/internal_agent_config.py
 app/startup/internal_agents.py
 app/startup/knowledge_builder.py
-app/startup/metrics.py
 app/startup/migrations.py
 app/startup/model_usage_backfill.py
 app/startup/operation_dependencies.py