Skip to content

Release Open Brain 1.0.0 #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benclawbot merged 3 commits into from
Jul 22, 2026
Merged

Release Open Brain 1.0.0 #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1245f1d
Prepare Open Brain 1.0.0 metadata
benclawbot Jul 22, 2026
1b60c6a
Add Open Brain 1.0.0 changelog
benclawbot Jul 22, 2026
414fc59
Document Open Brain 1.0.0 release
benclawbot Jul 22, 2026
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
38 changes: 38 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Changelog

All notable changes to Open Brain are documented in this file.

The project follows Semantic Versioning. Already-applied database migrations are immutable; upgrades add new migrations rather than editing migration history.

## [1.0.0] - 2026-07-22

### Added

- Canonical identities for users, agents, workspaces, projects, tasks, and sessions.
- Append-only, provenance-aware event ingestion with idempotency controls.
- Session lineage for resume, branch, compression, delegation, rewind, and close transitions.
- Structured assertions with supporting, contradicting, qualifying, and superseding evidence.
- Actionable context packets with trust labels, freshness, and token budgets.
- PostgreSQL and pgvector-backed semantic memory and hybrid retrieval.
- REST, MCP, CLI, dashboard, analytics, reporting, tagging, and entity extraction interfaces.
- Native Hermes memory provider with local write spooling, cached recall, and replay.
- Provider SDK and conformance suite.
- Medusa, Codex, and Claude Code lifecycle adapters with automatic source and `captured_by` attribution.
- Deployment authentication boundaries, secure configuration validation, request limits, health probes, structured diagnostics, and operator runbooks.
- Database retry behavior, concurrency coverage, pool-saturation handling, and migration matrices.
- Durable contradiction reconciliation, lifecycle review queues, and immutable automation receipts.
- Staged import preview, sealing, resumability, conflict reporting, rollback metadata, and atomic failure behavior.
- Retrieval feedback aggregation, diagnostics, proposal generation, explicit human approval, and immutable proposal/application receipts.
- Machine-readable `openbrain-release-check` readiness gate with JSON output and non-zero failure status.

### Changed

- Promoted package status from alpha `0.2.0` to production/stable `1.0.0`.
- Unified proposal review request contracts across lifecycle, consolidation, and pruning workflows.
- Hardened installer and updater behavior around migration checksums and data preservation.

### Operational requirements

A production deployment is ready only after automatic checks pass and operators explicitly attest that TLS, backups, restore drills, monitoring, and migration records have been verified. Open Brain deliberately does not infer these external controls from configuration alone.

[1.0.0]: https://github.com/benclawbot/open-brain/releases/tag/v1.0.0
171 changes: 72 additions & 99 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,40 @@
# Open Brain

> A model-independent personal memory and agent-continuity service. Open Brain preserves evidence, projects, tasks, decisions, outcomes, and long-term learning so different agents and interfaces can continue the same work.
> A model-independent personal memory and agent-continuity service for durable evidence, decisions, tasks, outcomes, and long-term learning across agents and interfaces.

[![Verify](https://github.com/benclawbot/open-brain/actions/workflows/verify.yml/badge.svg)](https://github.com/benclawbot/open-brain/actions/workflows/verify.yml)
[![License](https://img.shields.io/github/license/benclawbot/open-brain)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.0-blue)](CHANGELOG.md)

## What Open Brain does
## Overview

Open Brain is the durable knowledge layer behind AI agents. Agents remain responsible for reasoning, tools, browser or computer use, and execution. Open Brain is responsible for continuity, provenance, retrieval, and accumulated understanding.
Open Brain is the durable knowledge layer behind AI agents. Agents remain responsible for reasoning, tools, browser or computer use, and execution. Open Brain provides continuity, provenance, retrieval, lifecycle management, and accumulated understanding.

It provides:
It separates three concerns:

- semantic memory storage and hybrid search with PostgreSQL and pgvector;
- automatic tagging, entity extraction, trends, reports, REST, MCP, CLI, and dashboard interfaces;
- canonical user, agent, workspace, project, task, and session identities;
- append-only, provenance-aware events with idempotent ingestion;
- session lineage for new, reset, resume, branch, compression, delegation, and rewind transitions;
- structured assertions with supporting, contradicting, qualifying, and superseding evidence;
- compact actionable context packets with trust labels, freshness, and token budgets;
- a native upstream-compatible Hermes memory provider;
- a universal provider SDK with typed recall, remember, capability, scope, and lifecycle contracts;
- conformance-backed adapters for Medusa, Codex, and Claude Code;
- local write spooling and replay for supported offline-capable integrations;
- checksum-protected additive database migrations;
- a one-line installer and `openbrain update` command.
1. **Canonical evidence** — append-only events, imported records, sessions, tool results, and artifacts.
2. **Knowledge model** — current assertions, projects, tasks, decisions, procedures, and outcomes.
3. **Retrieval projections** — embeddings, indexes, revisions, caches, and context packets that can be rebuilt safely.

Imported or provider-supplied records are not silently promoted into truth. They retain authority and provenance until reconciliation determines whether they are durable facts, instructions, procedures, historical episodes, stale information, or inference.
Imported or provider-supplied records are never silently promoted into truth. They retain authority and provenance until reconciliation classifies them as durable facts, instructions, procedures, historical episodes, stale information, or inference.

## Capabilities

- PostgreSQL and pgvector-backed semantic memory and hybrid search
- canonical user, agent, workspace, project, task, and session identities
- append-only, provenance-aware events with idempotent ingestion
- session lineage for resume, branch, compression, delegation, rewind, and close transitions
- structured assertions with supporting, contradicting, qualifying, and superseding evidence
- compact actionable context packets with trust labels, freshness, and token budgets
- REST, MCP, CLI, dashboard, analytics, reports, tagging, and entity extraction
- native Hermes memory provider with local spool, cached recall, and replay
- universal provider SDK and conformance suite
- Medusa, Codex, and Claude Code lifecycle adapters
- staged, resumable imports with preview, sealing, conflicts, rollback metadata, and atomic failure behavior
- contradiction reconciliation, lifecycle automation, review queues, and immutable receipts
- retrieval feedback, diagnostics, self-improvement proposals, and explicit human approval
- checksum-protected additive database migrations
- production readiness validation through `openbrain-release-check`

## Architecture

Expand All @@ -52,12 +61,6 @@ Hermes Medusa Codex Claude Code other agents
PostgreSQL + pgvector
```

Open Brain separates:

1. **Canonical evidence** — append-only events, imported records, sessions, tool results, and artifacts.
2. **Knowledge model** — current assertions, projects, tasks, decisions, procedures, and outcomes.
3. **Retrieval projections** — embeddings, indexes, revisions, caches, and context packets that can be rebuilt safely.

## Agent integrations

| Agent | Integration | Lifecycle coverage | Offline behavior |
Expand All @@ -70,7 +73,7 @@ Open Brain separates:

The Codex and Claude Code bridges deliberately avoid undocumented local transcript formats. A host wrapper supplies stable session, workspace, version, and scope identifiers and calls explicit lifecycle methods.

Integration documentation:
Integration guides:

- [`docs/HERMES_INTEGRATION_ARCHITECTURE.md`](docs/HERMES_INTEGRATION_ARCHITECTURE.md)
- [`docs/HERMES_INTEGRATION_PROGRESS.md`](docs/HERMES_INTEGRATION_PROGRESS.md)
Expand All @@ -80,27 +83,26 @@ Integration documentation:

## Installation

### One-line installation
Open Brain requires Python 3.11+ and PostgreSQL. pgvector is recommended for semantic retrieval.

Linux, macOS, WSL, or a coding-agent shell with Python 3.11+:
For a reproducible v1.0.0 installation, review and run the release-pinned installer:

```bash
curl -fsSL https://raw.githubusercontent.com/benclawbot/open-brain/master/install.sh | sh
curl -fsSL https://raw.githubusercontent.com/benclawbot/open-brain/v1.0.0/install.sh | sh
```

The installer uses `pipx`, keeping Open Brain isolated from system Python packages.

Verify:

```bash
openbrain --version
openbrain --help
```

### Install from Hermes
The installer uses `pipx`, keeping Open Brain isolated from system Python packages.

### Hermes

```bash
curl -fsSL https://raw.githubusercontent.com/benclawbot/open-brain/master/install.sh | sh
openbrain install-hermes
export OPENBRAIN_URL=http://127.0.0.1:8000
hermes memory setup
Expand All @@ -118,17 +120,7 @@ export OPENBRAIN_TIMEOUT=3

If Open Brain is unavailable, Hermes continues operating. Writes are appended to `$HERMES_HOME/openbrain-spool.jsonl` and replayed later.

### Install through another coding agent

Give Claude Code, Codex, Medusa, OpenCode, or another shell-capable agent this instruction:

```text
Install Open Brain from https://github.com/benclawbot/open-brain using the repository's official install.sh script. Review the script first. After installation, run `openbrain --version`. If this is Hermes, also run `openbrain install-hermes`, set OPENBRAIN_URL, and configure the openbrain memory provider. Report failed steps without deleting existing data.
```

Agents without shell access can use the REST or MCP interfaces after Open Brain is deployed elsewhere.

### Development installation
### Development

```bash
git clone https://github.com/benclawbot/open-brain.git
Expand All @@ -138,25 +130,7 @@ python3 -m venv .venv
pip install -e '.[dev]'
```

## Updating

```bash
openbrain update
```

The updater upgrades the pipx-managed package, verifies migration checksums, applies only new migrations, and leaves existing data intact if migration execution fails.

Refresh an existing Hermes provider copy after upgrading:

```bash
openbrain install-hermes --force
```

Already-applied migrations must never be edited. Add a new migration instead.

## Database and configuration

Open Brain requires PostgreSQL. pgvector is recommended for semantic retrieval.
## Database and local stack

```env
DB_HOST=localhost
Expand All @@ -167,8 +141,6 @@ DB_PASSWORD=change-me
DB_TIMEZONE=auto
```

Start the complete local stack:

```bash
cp .env.example .env
docker compose up -d
Expand All @@ -183,6 +155,8 @@ python scripts/migrate.py
| Dashboard | `http://localhost:8501` |
| PostgreSQL | `localhost:5432` |

Already-applied migrations must never be edited. Add a new migration instead.

## CLI

```bash
Expand Down Expand Up @@ -223,20 +197,6 @@ POST /v1/context/feedback

Context packets contain selected current state rather than raw transcript fragments. Items carry labels such as `user_confirmed`, `tool_observed`, `curated_memory`, `inferred`, `stale`, or `contradicted`.

## Provider SDK and conformance

The provider SDK normalizes:

- provider identity and version;
- declared capabilities;
- recall and remember requests;
- canonical user, project, and task scope;
- deterministic idempotency keys;
- authority labels;
- health checks and transport behavior.

`run_provider_conformance()` validates descriptor integrity, declared capabilities, scoped recall and remember behavior, and duplicate-safe ingestion. Adapters can call `require_success()` to fail validation with a structured report.

## Memory lifecycle

```text
Expand All @@ -253,18 +213,36 @@ Open Brain prunes retrieval before storage. Old evidence can leave hot retrieval

Typical authority ordering:

1. direct user statement;
2. user-curated memory;
3. tool observation;
4. provider inference;
5. Open Brain inference;
6. assistant claim.
1. direct user statement
2. user-curated memory
3. tool observation
4. provider inference
5. Open Brain inference
6. assistant claim

Sensitive records can carry sensitivity and retention classifications. Provider inference remains distinguishable from user-confirmed truth.

Review `install.sh` before execution in high-security environments. For reproducible deployment, pin installation to a reviewed release tag rather than `master`.
Review `install.sh` before execution in high-security environments. Use a reviewed release tag rather than the moving `master` branch for reproducible deployment.

## Production readiness

Run the machine-readable gate before deployment:

```bash
openbrain-release-check --help
```

The gate validates production mode, authentication, API-key strength, and explicit CORS configuration. It also requires operator attestations for controls that cannot be inferred safely from application configuration:

- TLS termination verified
- backups verified
- restore drill completed
- monitoring enabled
- migration records confirmed

## Development and validation
A deployment is not certified merely because configuration files exist. See [`docs/RELEASE_READINESS.md`](docs/RELEASE_READINESS.md).

## Validation

```bash
pip install -e '.[dev]'
Expand All @@ -273,15 +251,7 @@ pytest -q
python -m build
```

GitHub Actions validates:

- package installation;
- PostgreSQL and pgvector migrations;
- the full test suite;
- provider conformance tests;
- wheel creation;
- installed CLI execution;
- native Hermes provider copying and smoke tests.
GitHub Actions validates package installation, PostgreSQL and pgvector migrations, the full test suite, provider conformance, wheel creation, installed CLI execution, and Hermes provider installation smoke tests.

## Project structure

Expand All @@ -292,8 +262,9 @@ src/
├── continuity/ event, identity, and session contracts
├── context/ actionable context and packet builder
├── db/ persistence, migrations, and queries
├── importers/ Hermes and provider import adapters
├── importers/ staged and provider imports
├── providers/ universal provider SDK and conformance
├── release/ production readiness checks
├── openbrain_hermes_plugin/ standalone Hermes memory provider
├── openbrain_medusa_adapter/ Medusa lifecycle adapter
├── openbrain_codex_adapter/ Codex lifecycle adapter
Expand All @@ -304,11 +275,13 @@ src/
└── notifications/ notification integrations
```

## Status
## Release status

**Open Brain 1.0.0 is the first production/stable release.** The coordinated production-readiness train delivered deployment hardening, database resilience, real adapter host wiring, durable reconciliation, staged imports, unified proposal review workflows, and a machine-readable release gate.

Open Brain 0.2 is alpha software. Implemented foundations now include the continuity model, Hermes bootstrap imports, actionable context APIs, native Hermes provider, universal provider SDK, conformance runner, Medusa adapter, Codex adapter, Claude Code adapter, installer, updater, and package validation path.
Production readiness still depends on the target environment. Operators must run the readiness gate and verify external controls such as TLS, backups, restore drills, and monitoring before serving real data.

Remaining maturity work includes broader database concurrency coverage, staged-import rollback metadata, richer reconciliation automation, lifecycle policy automation, adapter packaging and host wiring ergonomics, production deployment hardening, and self-improvement proposal workflows.
See [`CHANGELOG.md`](CHANGELOG.md) for release details.

## License

Expand Down
8 changes: 4 additions & 4 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,17 @@ build-backend = "setuptools.build_meta"

[project]
name = "openbrain"
version = "0.2.0"
version = "1.0.0"
description = "Shared personal memory, agent continuity, and actionable context"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [
{name = "Tom", email = "tom@example.com"}
{name = "Ben Clawbot"}
]
keywords = ["memory", "agents", "semantic-search", "mcp", "postgres", "pgvector"]
classifiers = [
"Development Status :: 3 - Alpha",
"Development Status :: 5 - Production/Stable",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3.11",
Expand Down Expand Up @@ -63,4 +63,4 @@ include = ["src*", "config*"]
[tool.setuptools.package-data]
config = ["*.yaml", "*.yml"]
"src.db" = ["migrations/*.sql"]
"src.openbrain_hermes_plugin" = ["plugin.yaml", "README.md"]
"src.openbrain_hermes_plugin" = ["plugin.yaml", "README.md"]
Loading