From 5f45b3b2f27c9171896f13e5b156b41a258c8d08 Mon Sep 17 00:00:00 2001 From: Alfie Lambert <39379701+alfielambert@users.noreply.github.com> Date: Tue, 10 Nov 2026 15:00:43 +0000 Subject: [PATCH] Add architecture diagram, CI and fix OpenLore links - Replace the ASCII architecture flows in the README with an SVG (light and dark mode) in the OpenLore diagram style - Add a GitHub Actions workflow running pytest on Ubuntu and macOS, Python 3.10 and 3.12, plus README badges - Treat a zombie grandchild as dead in the timeout test: a killed orphan stays a zombie until init reaps it, which some container inits never do - Point OpenLore links at aakarim/OpenLore (go-openlore now redirects) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_019YV9XDSehfhz5Ro9PrqaTs --- .github/workflows/tests.yml | 22 +++++++ README.md | 20 +++--- docs/architecture.md | 2 +- docs/assets/how-it-works.svg | 108 +++++++++++++++++++++++++++++++ docs/openlore-integration.md | 4 +- tests/test_subprocess_timeout.py | 18 +++++- 6 files changed, 158 insertions(+), 16 deletions(-) create mode 100644 .github/workflows/tests.yml create mode 100644 docs/assets/how-it-works.svg diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..b1588c9 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,22 @@ +name: tests + +on: + push: + branches: [main] + pull_request: + +jobs: + pytest: + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest] + python-version: ["3.10", "3.12"] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + - run: pip install -e '.[dev]' + - run: pytest -q diff --git a/README.md b/README.md index 43ab544..841326a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # Second Brain +[![tests](https://github.com/alfielambert/second-brain/actions/workflows/tests.yml/badge.svg)](https://github.com/alfielambert/second-brain/actions/workflows/tests.yml) +[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg) + Most second brains store information. This one decides what deserves to become knowledge. @@ -78,19 +82,13 @@ this" by walking the chain back to the original evidence. See ## Architecture -**Local mode** - everything on your machine, nothing required beyond this repo: - -``` -Sources -> Connectors -> Claim Store -> KEP -> Governed Knowledge -> Local AI -``` +

+ Evidence from X bookmarks, notes and connectors becomes append-only claims. KEP decides whether each claim is auto-applied, held for approval or logged as a signal. Governed Markdown knowledge is compiled for a local AI, or served to many agents through OpenLore. +

-**Multiplayer mode** - once more than one agent needs the same knowledge: - -``` -Sources -> Connectors -> Claim Store -> KEP -> Governed Knowledge -> OpenLore -> Multiple AI agents -``` +**Local mode** runs everything on your machine and needs nothing beyond this repo. **Multiplayer mode** adds OpenLore at the end, once more than one agent needs the same knowledge. -[OpenLore](https://github.com/aakarim/go-openlore) is an open-source +[OpenLore](https://github.com/aakarim/OpenLore) is an open-source knowledge server for AI agents. **Second Brain creates and governs knowledge. OpenLore distributes governed knowledge to agents.** The two are cleanly separable, and OpenLore is entirely optional - you do not diff --git a/docs/architecture.md b/docs/architecture.md index a3bdfd8..5d03103 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -40,7 +40,7 @@ Sources -> Connectors -> Claim Store -> KEP -> Governed Knowledge -> OpenLore -> ``` The only thing that changes is the last step. OpenLore -(https://github.com/aakarim/go-openlore) is a separate, already +(https://github.com/aakarim/OpenLore) is a separate, already open-source, MIT-licensed knowledge server - not a proprietary add-on. It knows nothing about claims, KEP, or this schema; it just serves a directory of markdown+frontmatter over SSH/MCP/HTTP to authenticated identities. diff --git a/docs/assets/how-it-works.svg b/docs/assets/how-it-works.svg new file mode 100644 index 0000000..da8c890 --- /dev/null +++ b/docs/assets/how-it-works.svg @@ -0,0 +1,108 @@ + + How Second Brain works + Evidence from X bookmarks, captured notes and your own connectors becomes append-only claims. KEP, a deterministic lookup table, decides whether each claim is auto-applied, held for your approval or logged as a weak signal. Approved claims become governed Markdown knowledge, which is compiled into context for a local AI or served to many agents through OpenLore. + + + + + + + + + + + Evidence + + X bookmarks + OAuth sync + + Captured notes + inbox/*.md + + Your connectors + Gmail, Notion... + + + + + + + + Claim Store + append-only + Every claim keeps + its evidence. Nothing + is overwritten. + claim → event + claim → event + + + + + + KEP + a lookup table, not a model call + + Auto-apply + confident update + + Ask you first + new, conflicting, structural + + Log a signal + too weak to keep yet + + + + + Governed knowledge + + vault/ + Decisions/ + People/ + Companies/ + Insights/ + Plain Markdown + with provenance. + + + + + + Your agents + + Local AI + compiled pack + + OpenLore + many agents + optional + + + Evidence is collected. Knowledge is governed. Context is compiled. Agents only see knowledge that passed governance. + diff --git a/docs/openlore-integration.md b/docs/openlore-integration.md index 31a91fc..1346cdc 100644 --- a/docs/openlore-integration.md +++ b/docs/openlore-integration.md @@ -18,7 +18,7 @@ synchronization problem wearing a knowledge-management costume. ## What OpenLore is -[OpenLore](https://github.com/aakarim/go-openlore) is a separate, +[OpenLore](https://github.com/aakarim/OpenLore) is a separate, already-open-source (MIT), agent-native knowledge server. It serves a directory of markdown+frontmatter to authenticated agent identities over SSH, MCP (HTTP or stdio), and a JSON REST API - with per-identity scoped @@ -42,7 +42,7 @@ with no manual copying. go install github.com/aakarim/go-openlore/cmd/openlore@latest ``` -(Requires Go 1.26+. See the [OpenLore README](https://github.com/aakarim/go-openlore#installation) for other install methods.) +(Requires Go 1.26+. See the [OpenLore README](https://github.com/aakarim/OpenLore/blob/main/docs/start/quickstart.md#install) for other install methods.) ### 2. Point it at governed knowledge diff --git a/tests/test_subprocess_timeout.py b/tests/test_subprocess_timeout.py index 19d341f..d6bcb44 100644 --- a/tests/test_subprocess_timeout.py +++ b/tests/test_subprocess_timeout.py @@ -72,5 +72,19 @@ def test_grandchild_process_does_not_survive_the_timeout_kill(): if content: # the grandchild got far enough to write its pid before being killed grandchild_pid = int(content) - with pytest.raises(ProcessLookupError): - os.kill(grandchild_pid, 0) # signal 0: just checks if the process exists + assert not _is_running(grandchild_pid) + + +def _is_running(pid): + """True if pid exists and is not a zombie. A killed orphan stays a + zombie until init reaps it, and some container inits never do, so + os.kill(pid, 0) alone would report a dead process as alive.""" + try: + os.kill(pid, 0) # signal 0: just checks if the process exists + except ProcessLookupError: + return False + try: + with open(f"/proc/{pid}/stat") as f: + return f.read().rsplit(")", 1)[1].split()[0] != "Z" + except FileNotFoundError: # no /proc (macOS): trust os.kill + return True