diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..872ad37 --- /dev/null +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index 4f85d26..b5d36b7 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 | @@ -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) @@ -80,16 +83,14 @@ 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 @@ -97,10 +98,11 @@ 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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -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]' @@ -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 @@ -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 @@ -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 diff --git a/pyproject.toml b/pyproject.toml index 96c58fe..6f2e51a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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", @@ -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"] \ No newline at end of file