diff --git a/README.md b/README.md index b5d36b7..81102b1 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,20 @@ +

+ Open Brain — persistent memory, continuous learning, and context-aware intelligence for coding agents +

+ # Open Brain -> A model-independent personal memory and agent-continuity service for durable evidence, decisions, tasks, outcomes, and long-term learning across agents and interfaces. +> The user-owned memory and continuity layer for coding agents: durable evidence, decisions, tasks, outcomes, and reviewed learning across models, projects, 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) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit) [![Version](https://img.shields.io/badge/version-1.0.0-blue)](CHANGELOG.md) ## 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 provides continuity, provenance, retrieval, lifecycle management, and accumulated understanding. +Open Brain gives coding agents a durable, model-independent brain. It stores semantic memory in PostgreSQL and pgvector, preserves where knowledge came from, follows work across sessions and agents, and assembles compact context for the next task. + +Open Brain is the memory and intelligence layer, not the agent runtime. Connected agents remain responsible for reasoning, filesystem and terminal access, browser or computer use, and execution. Native integrations currently exist for Hermes, Medusa, Codex, and Claude Code; other agents connect through REST, MCP, the CLI, or the provider SDK. It separates three concerns: @@ -18,23 +24,27 @@ It separates three concerns: 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` +## How the banner maps to the code + +| Promise | Current implementation | +|---|---| +| **Persistent memory** | PostgreSQL and pgvector semantic memory, hybrid search, canonical identities, append-only events, structured assertions, provenance, and exact agent attribution | +| **Continuous learning** | Retrieval feedback, contradiction reconciliation, compaction, and review queues for consolidation, lifecycle, and pruning proposals; durable changes require explicit acceptance and leave immutable receipts | +| **Context-aware intelligence** | Trust-labelled context packets use project, task, session, freshness, diversity, and token-budget signals, with revision-aware caching and feedback scoring | +| **Works across agents** | Native Hermes, Medusa, Codex, and Claude Code integrations plus REST, MCP, CLI, and a provider SDK with a conformance suite for additional hosts | + +The Mem0, Honcho, and Hindsight integrations are provenance-preserving import adapters, not interchangeable live storage backends. Agents without a native adapter use the generic interfaces above. + +## What is implemented + +| Area | Capabilities | +|---|---| +| Memory and retrieval | Semantic and filtered search, recent and related memory, entities, tags, trends, weekly reports, context packets, and retrieval feedback | +| Continuity and knowledge | Canonical user, agent, workspace, project, task, and session identities; session lineage; idempotent events; evidence-backed assertions; decisions, procedures, and outcomes | +| Learning and governance | Contradiction reconciliation, memory compaction, bounded maintenance, proposal generation, human review, reversible consolidation, lifecycle transitions, conservative pruning, and immutable automation receipts | +| Interfaces | FastAPI REST service and OpenAPI docs, MCP tools, CLI, Streamlit dashboard, provider SDK, and conformance checks | +| Imports and connectors | Staged and resumable imports for Hermes memory, context, sessions, skills, and cron jobs; Mem0, Honcho, and Hindsight exports; file watcher, Claude Code logs, Gmail Takeout, Telegram, and WhatsApp exports | +| Operations | API-key authentication, request-size and rate limits, explicit CORS, structured diagnostics, health and readiness probes, retry-aware database access, checksum-protected migrations, and `openbrain-release-check` | ## Architecture @@ -77,13 +87,13 @@ Integration guides: - [`docs/HERMES_INTEGRATION_ARCHITECTURE.md`](docs/HERMES_INTEGRATION_ARCHITECTURE.md) - [`docs/HERMES_INTEGRATION_PROGRESS.md`](docs/HERMES_INTEGRATION_PROGRESS.md) -- [`docs/MEDUSA_ADAPTER.md`](docs/MEDUSA_ADAPTER.md) +- [`docs/MEDUSA_INTEGRATION.md`](docs/MEDUSA_INTEGRATION.md) - [`docs/CODEX_ADAPTER.md`](docs/CODEX_ADAPTER.md) - [`docs/CLAUDE_CODE_ADAPTER.md`](docs/CLAUDE_CODE_ADAPTER.md) ## Installation -Open Brain requires Python 3.11+ and PostgreSQL. pgvector is recommended for semantic retrieval. +Open Brain requires Python 3.11+ and PostgreSQL with pgvector. For a reproducible v1.0.0 installation, review and run the release-pinned installer: @@ -143,17 +153,18 @@ DB_TIMEZONE=auto ```bash cp .env.example .env -docker compose up -d -python scripts/migrate.py +docker compose up -d --build +docker compose ps ``` | Service | Address | |---|---| | REST API | `http://localhost:8000` | | API documentation | `http://localhost:8000/docs` | -| MCP server | `http://localhost:8080` | | Dashboard | `http://localhost:8501` | -| PostgreSQL | `localhost:5432` | +| PostgreSQL from the host | `localhost:5433` | + +The API container applies pending migrations during startup. Containers reach PostgreSQL as `postgres:5432`; programs running on the host use the published port `localhost:5433`. Already-applied migrations must never be edited. Add a new migration instead. @@ -170,11 +181,22 @@ openbrain install-hermes openbrain update ``` +## MCP + +The MCP server uses the standard stdio transport: + +```bash +python -m src.main +``` + +It exposes `memory_search`, `memory_store`, `memory_get_related`, `memory_get_entity`, `memory_today`, `memory_stats`, and `memory_weekly_report`. Configure an MCP-capable host to launch that command from the repository or installed environment. + ## REST API -Semantic-memory endpoints: +The complete, live contract is available through the OpenAPI documentation at `http://localhost:8000/docs`. Core semantic-memory endpoints include: ```text +GET /memories POST /memories POST /memories/search GET /memories/{memory_id} @@ -191,10 +213,14 @@ POST /v1/identities/resolve POST /v1/sessions/open POST /v1/sessions/{session_id}/close POST /v1/imports/hermes/markdown +GET /v1/imports/providers +POST /v1/imports/providers POST /v1/context POST /v1/context/feedback ``` +Reviewed automation is exposed under `/v1/lifecycle`, `/v1/consolidation`, `/v1/pruning`, `/v1/compaction`, and `/v1/maintenance`. + 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`. ## Memory lifecycle @@ -260,7 +286,12 @@ src/ ├── api/ REST endpoints ├── cli/ command-line interface ├── continuity/ event, identity, and session contracts -├── context/ actionable context and packet builder +├── context/ context packets, caching, feedback, and revisions +├── lifecycle/ evidence-backed knowledge-state proposals +├── consolidation/ duplicate and overlapping assertion proposals +├── pruning/ conservative archival and restoration policies +├── compaction/ durable memory compaction +├── maintenance/ bounded maintenance orchestration ├── db/ persistence, migrations, and queries ├── importers/ staged and provider imports ├── providers/ universal provider SDK and conformance @@ -272,6 +303,7 @@ src/ ├── analytics/ trends and reports ├── connectors/ source connectors ├── extractors/ entities and tagging +├── sandbox/ optional isolated command execution └── notifications/ notification integrations ``` diff --git a/docs/assets/openbrain-hero.png b/docs/assets/openbrain-hero.png new file mode 100644 index 0000000..6ae0af4 Binary files /dev/null and b/docs/assets/openbrain-hero.png differ