Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,13 @@ All notable changes to the brain kernel. Versions correspond to
shipped roadmap slices (`wiki/brain/roadmap.md` holds the full
narrative; the ADR shelf holds the decisions).

## 0.31.3, 2026-10-25
The PyPI page reads as the published project.
- The README is titled `tended`, carries a PyPI badge, and links its
screenshot and wiki pages by absolute URL so they resolve on PyPI.
- `pyproject.toml` declares the project URLs (repository, changelog,
issues), so PyPI links back to GitHub.

## 0.31.2, 2026-10-25
Published on PyPI as `tended`, so `uvx tended init my-wiki` creates a
working instance anywhere.
Expand Down
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
# brain
# tended

[![PyPI](https://img.shields.io/pypi/v/tended)](https://pypi.org/project/tended/)

**A knowledge base your coding agent maintains for you.** Point it at
your repos, docs, and decisions; the agent keeps a synthesized,
browsable wiki of what's true, what was decided, and why — accurate
enough to regenerate the code from, surface cross-team overlaps, and
serve as any agent's working memory.

![the app — the rendered knowledge under an ambient health strip](docs/workbench.png)
![the app — the rendered knowledge under an ambient health strip](https://raw.githubusercontent.com/misabegovic/tended/main/docs/workbench.png)

## How it works — three ideas

Expand Down Expand Up @@ -320,8 +322,8 @@ personal data, no boilerplate.
|-------------------|----------------------|----------------------------------------------------------------|
| Datadog / Langfuse | ✅ pull connectors | Monitor+SLO state / prompt inventory → snapshots + state extracts for view tiles. |
| GitHub / Notion / Slack | ✅ pull connectors | Snapshot-writers: immutable files into `sources/`, inbox items out. Configure `connectors:` in `brain.config.yml` + read-only tokens in `.env`. |
| Structure | ✅ pull connector | Deterministic code-shape snapshots (source inventory + Python symbols) → architectural-drift inbox items via baseline diff; drift auto-clears once a wiki page cites the snapshot. No network / binary / LLM; read-only git with a clean-tree guard. Configure `connectors.structure.repos`. `brain.py structure findings` turns those facts into conservative, computed findings (`oversized-package`, `god-file`, and `symbol-blindness`, which reports the share of a repo the substrate cannot see past file level — symbol visibility is Python-only). `brain.py structure judge` records accepted / rejected / noise into a write-on-judgment ledger with **no pending state**: absence means unjudged, not queued. Per [`wiki/brain/adrs/structure-findings-and-verdict-ledger.md`](wiki/brain/adrs/structure-findings-and-verdict-ledger.md). |
| Architecture graph | ⬜ optional tier | `brain.py enola` — cluster snapshots over the same repos via the external [enola](https://github.com/enola-labs/enola) binary, with committed receipts in `wiki/_state/enola/`, drift reporting, merged explainer findings, a verdict ledger, `impact <symbol>` (fan-in / fan-out / named callers) from the on-disk fact set, `baseline` + `check` (grades a change against a pinned before — **reports, never gates**; its `declined` verdict means the snapshots were not comparable and reads as *not asked*, never as a pass), `coverage` (which cross-repo edges resolved, so a genuinely isolated service reads apart from one whose edges could not be followed), `explain`, `doctor` (whether the session hooks are *firing*, not merely configured), and an experimental `history` family (`log` / `show` / `diff` / `blame` / `gc`) that answers *when* something entered the architecture — a question a snapshot structurally cannot. The wiki itself compiles into this graph: every page carries a derived `enola_intent:` block (`brain.py intent stamp`, auto-restamped by the pre-commit hook, gated by the `intent-page-block` detector and preflight), repo citations become page-to-code anchors, and `enola govern <target>` answers the reverse query — *which compiled pages govern this file or symbol* (with relation trails), or, for a page path, *which code its anchors cover*. Verdict compilation went live with enola v0.3.9 (2026-08-06, the first release carrying the upstream intent standard from enola-labs/enola#197); under an older pinned binary the blocks still compile forward-compatibly and `govern` answers *no knowledge pages compiled* — a named skip, never an error. See [`wiki/brain/topics/intent-compilation.md`](wiki/brain/topics/intent-compilation.md). Session hooks are available via `enola install --hooks`: a baseline pinned at session start and a regression reported at session end, which is the one place the graph speaks unasked. The **ceiling** to the structure connector's **floor**: it answers what in-kernel extraction cannot, and it is allowed to be absent — nothing may depend on it being installed. Note the trade the other way: the connector reads `git ls-files` and therefore sees only *tracked* files, while enola walks the filesystem — so the ignore list is the only thing between the graph and a vendored dependency tree. The defaults exclude `.venv`, `site-packages`, `node_modules`, build output and the usual caches; extend them per repo via `connectors.enola.ignore`. The cluster is generated from `brain.config.yml` (`active_repos` + `connectors.enola.repos`); the generated `mcp-arch.yaml` and all `.enola/` artifacts are gitignored. |
| Structure | ✅ pull connector | Deterministic code-shape snapshots (source inventory + Python symbols) → architectural-drift inbox items via baseline diff; drift auto-clears once a wiki page cites the snapshot. No network / binary / LLM; read-only git with a clean-tree guard. Configure `connectors.structure.repos`. `brain.py structure findings` turns those facts into conservative, computed findings (`oversized-package`, `god-file`, and `symbol-blindness`, which reports the share of a repo the substrate cannot see past file level — symbol visibility is Python-only). `brain.py structure judge` records accepted / rejected / noise into a write-on-judgment ledger with **no pending state**: absence means unjudged, not queued. Per [`wiki/brain/adrs/structure-findings-and-verdict-ledger.md`](https://github.com/misabegovic/tended/blob/main/wiki/brain/adrs/structure-findings-and-verdict-ledger.md). |
| Architecture graph | ⬜ optional tier | `brain.py enola` — cluster snapshots over the same repos via the external [enola](https://github.com/enola-labs/enola) binary, with committed receipts in `wiki/_state/enola/`, drift reporting, merged explainer findings, a verdict ledger, `impact <symbol>` (fan-in / fan-out / named callers) from the on-disk fact set, `baseline` + `check` (grades a change against a pinned before — **reports, never gates**; its `declined` verdict means the snapshots were not comparable and reads as *not asked*, never as a pass), `coverage` (which cross-repo edges resolved, so a genuinely isolated service reads apart from one whose edges could not be followed), `explain`, `doctor` (whether the session hooks are *firing*, not merely configured), and an experimental `history` family (`log` / `show` / `diff` / `blame` / `gc`) that answers *when* something entered the architecture — a question a snapshot structurally cannot. The wiki itself compiles into this graph: every page carries a derived `enola_intent:` block (`brain.py intent stamp`, auto-restamped by the pre-commit hook, gated by the `intent-page-block` detector and preflight), repo citations become page-to-code anchors, and `enola govern <target>` answers the reverse query — *which compiled pages govern this file or symbol* (with relation trails), or, for a page path, *which code its anchors cover*. Verdict compilation went live with enola v0.3.9 (2026-08-06, the first release carrying the upstream intent standard from enola-labs/enola#197); under an older pinned binary the blocks still compile forward-compatibly and `govern` answers *no knowledge pages compiled* — a named skip, never an error. See [`wiki/brain/topics/intent-compilation.md`](https://github.com/misabegovic/tended/blob/main/wiki/brain/topics/intent-compilation.md). Session hooks are available via `enola install --hooks`: a baseline pinned at session start and a regression reported at session end, which is the one place the graph speaks unasked. The **ceiling** to the structure connector's **floor**: it answers what in-kernel extraction cannot, and it is allowed to be absent — nothing may depend on it being installed. Note the trade the other way: the connector reads `git ls-files` and therefore sees only *tracked* files, while enola walks the filesystem — so the ignore list is the only thing between the graph and a vendored dependency tree. The defaults exclude `.venv`, `site-packages`, `node_modules`, build output and the usual caches; extend them per repo via `connectors.enola.ignore`. The cluster is generated from `brain.config.yml` (`active_repos` + `connectors.enola.repos`); the generated `mcp-arch.yaml` and all `.enola/` artifacts are gitignored. |

| GitHub | via `gh` CLI | Pre-allowed in `.claude/settings.json`. |
| MCP | ✅ `tools/brain-mcp.py` | Read-only; stdio or `--http` (loopback Host + Origin checks); `BRAIN_SERVING=1` excludes ai-suggestion drafts across *every* read surface (MCP, serve JSON API, search CLI, static build) + query audit log. |
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.31.2
0.31.3
6 changes: 6 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,12 @@ dynamic = ["version"]
cluster = ["scikit-learn"]
full = ["tiktoken", "datasette", "pytest", "scikit-learn"]

[project.urls]
Homepage = "https://github.com/misabegovic/tended"
Repository = "https://github.com/misabegovic/tended"
Changelog = "https://github.com/misabegovic/tended/blob/main/CHANGELOG.md"
Issues = "https://github.com/misabegovic/tended/issues"

[project.scripts]
tended = "tended.cli:main"

Expand Down
Loading