rationalevault 1.0.0__tar.gz

rationalevault-1.0.0/.env.example

@@ -0,0 +1,13 @@
+# RationaleVault — Environment Configuration
+# Copy to .env and adjust values for your environment.
+
+# ── PostgreSQL ────────────────────────────────────────────────────────────────
+RELAY_DB_HOST=localhost
+RELAY_DB_PORT=5432
+RELAY_DB_NAME=relay
+RELAY_DB_USER=relay
+RELAY_DB_PASSWORD=relay
+
+# ── Testing ───────────────────────────────────────────────────────────────────
+# Set to "1" to run tests that require a live PostgreSQL database.
+RELAY_DB_TEST_ENABLED=0

rationalevault-1.0.0/.gitattributes

@@ -0,0 +1,9 @@
+# Normalize line endings to LF in the repository
+* text=auto eol=lf
+
+# Binary files
+*.whl binary
+*.tar.gz binary
+*.png binary
+*.jpg binary
+*.db binary

rationalevault-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to help us improve RationaleVault
+title: '[BUG] '
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Reproduction Steps**
+1. Run command '...'
+2. Code configuration '...'
+3. See error '...'
+
+**System Diagnostics (Required)**
+Please run the diagnostics tool and attach the output below:
+```bash
+rationalevault doctor
+```
+
+**Environment details:**
+- OS: [e.g. macOS, Windows, Linux]
+- Python version: [e.g. 3.12]
+- RationaleVault version: [e.g. 1.0.0rc2]
+- Database backend: [SQLite, PostgreSQL]
+
+**Additional context**
+Add any other context or logs about the problem here.

rationalevault-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea or enhancement for RationaleVault
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex: "I'm frustrated when..."
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or mockups about the feature request here.

rationalevault-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Description
+Provide a summary of the changes and the problem solved.
+
+## Related Issues
+Fixes #[issue-number]
+
+## Verification Checklist
+All submissions must pass the following release gates:
+
+- [ ] **pytest passes**: All 283 unit and integration tests run successfully.
+- [ ] **rationalevault doctor passes**: The diagnostics suite verifies database connections and projection chains.
+- [ ] **rationalevault evaluate passes**: The evaluation pipeline successfully verifies exit gates.
+- [ ] **Wheel build check**: `python -m build` compiles the project correctly without errors.
+- [ ] **Documentation updated**: Any interface or logic changes are documented in the `docs/` folder.

rationalevault-1.0.0/.github/workflows/verify.yml

@@ -0,0 +1,45 @@
+name: Verify
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+        pip install -e ".[dev]"
+    - name: Run pytest
+      run: pytest
+    - name: Run rationalevault doctor (editable)
+      run: python -m rationalevault.cli.main doctor
+    - name: Run rationalevault evaluate
+      run: python -m rationalevault.cli.main evaluate
+    - name: Build package wheel
+      run: python -m build
+    - name: Install from wheel
+      run: |
+        pip uninstall -y rationalevault
+        pip install dist/*.whl
+    - name: Run installed doctor (CWD-agnostic verification)
+      run: |
+        cd /tmp
+        rationalevault doctor
+    - name: Run installed evaluate (CWD-agnostic verification)
+      run: |
+        cd /tmp
+        rationalevault evaluate
+    - name: Verify release manifest version
+      run: |
+        python -c "import json; manifest = json.load(open('.rationalevault/reports/release_manifest.json')); assert manifest['rationalevault_version'] == '1.0.0', f'Invalid version: {manifest[\"rationalevault_version\"]}'; assert manifest['schema_version'] == '1.0', f'Invalid schema: {manifest[\"schema_version\"]}'"

rationalevault-1.0.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Environment
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Docker volumes (local data)
+docker/postgres/data/
+
+# RationaleVault scratch
+scratch/
+
+# RationaleVault runtime data (generated — do not commit)
+.relay/
+.rationalevault/
+rationalevault/evaluation/reports/
+

rationalevault-1.0.0/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to RationaleVault will be documented in this file.
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.0.0] — 2026-06-22
+
+### Added
+- Renamed the entire project package namespace from `relay` to `rationalevault`.
+- Created dual entrypoint and unified CLI binary `rationalevault` as the sole public command.
+- Integrated examples directly into the package (`rationalevault.examples`) so they can be run from any CWD.
+
+### Fixed
+- Fixed CWD-sensitive asset loading in `rationalevault doctor` and `rationalevault evaluate` by utilizing `importlib.resources` instead of relative workspace paths. This allows running active diagnostics and evaluations on arbitrary directories after wheel installation.
+
+---
+
+## [1.0.0rc2] — 2026-06-22
+
+### Changed
+- Centralized package and schema version into `relay/__init__.py`.
+- Formatted version as PEP 440-compliant `1.0.0rc2`.
+- `rationalevault doctor` and `rationalevault evaluate` now both consume the central `__version__` and `SCHEMA_VERSION` constants.
+
+---
+
+## [1.0.0rc1] — 2026-06-22
+
+### Sprint I8 — Release Hardening
+- **Unified Evaluation Framework**: Single CLI entry point (`rationalevault evaluate`) that validates Memory, Knowledge, Context, Compilers, Continuity, Graph, and Examples in a single pass.
+- **Active Diagnostics**: `rationalevault doctor` checks storage connection pools, evaluation assets, compiler adapters, and runs an end-to-end **Projection Chain Verification** (Event → Memory → Knowledge → Graph → Context → Compiler).
+- **Release Manifest**: Outputs a machine-readable `release_manifest.json` snapshot at `.relay/reports/release_manifest.json` and a markdown summary at `.relay/reports/report.md`.
+- **Installation Validator**: `relay.evaluation.validate_install` performs critical import verification across all pipeline stages.
+
+### Sprint I7.5 — Knowledge Graph Projection
+- **GraphProjection**: Deterministic, SHA-256-identified graph projection over all synthesized KnowledgeObjects and KnowledgeRelations.
+- **Graph Evaluation**: Node coverage, edge coverage, referential integrity, determinism, orphan percentage, and connected component metrics with exit gate validation.
+- **Graph Exports**: Mermaid, NetworkX, and GraphML serialization formats.
+- **`rationalevault graph`** CLI subcommand: `build`, `stats`, `show`, `path`, `neighbors`.
+
+### Sprint I7 — Multi-Agent Continuity Validation
+- **Continuity Benchmarks**: Structured benchmark schema for agent handoff verification with artifact canonical/alias matching.
+- **Corpus Builder**: Automated handoff corpus generation from conversation transcripts.
+- **Continuity Evaluator**: Goal recall, decision recall, task recall, context gain, and rationale recall metrics.
+- **`rationalevault context`** CLI subcommand with `--evaluate` mode for continuity analysis.
+
+### Sprint I6–I6.5 — Agent Compiler Framework
+- **Agent Compiler Registry**: Abstract compiler interface (`ContextCompilerBase`) and plugin registry for Claude, OpenCode, and Cursor adapters.
+- **Claude Compiler**: Produces structured markdown with open questions, active tasks, decisions, and a resumption prompt.
+- **OpenCode Compiler**: YAML-structured output optimized for structured agent contexts.
+- **Cursor Compiler**: Context-aware output for IDE-integrated agents.
+- **Compiler Evaluator**: Section coverage, keyword coverage, determinism, and compression ratio evaluation.
+
+### Sprint I5–I5.5 — Context Construction
+- **Context Compiler**: Query-intent-aware profile-based slot allocation blending events, memories, and knowledge into unified `ContextPackage`.
+- **Query Profiles**: `context_construction`, `knowledge_review`, `decision_audit`, `default`, `diagnostic`.
+- **Retrieval Profile Planner**: Slot budget allocation across source types for each profile.
+- **Context Evaluation**: Completeness, source traceability, source balance, precision, redundancy, and timing budget metrics.
+- **`rationalevault context`** CLI subcommand.
+
+### Sprint I4–I4.5 — Knowledge Synthesis & Evaluation
+- **Knowledge Synthesizer**: Derives structured `KnowledgeObject` instances (architecture principles, project invariants, implementation patterns, constraints, lessons learned) from memory records.
+- **Knowledge Provider**: SQLite-backed persistent knowledge store.
+- **Knowledge Evaluation**: Density, coverage, provenance percentage, contradiction detection, freshness, stability, and determinism metrics.
+- **Knowledge Benchmark Schema**: Structured benchmark format for precision, semantic recall, identity recall, F1, and type coverage.
+- **`rationalevault knowledge`** CLI subcommand.
+
+### Sprint I3–I3.5 — Retrieval Intelligence
+- **Ranked Retrieval**: Multi-factor retrieval scoring (priority, recency, reference count, confidence, lifecycle penalty).
+- **Query Intent Analysis**: Automatic query profiling with intent-based source weighting.
+- **Citation Builder**: Structured `MemoryCitation` with full retrieval path and reason codes.
+- **Retrieval Benchmarks**: Precision@K, Recall@K, NDCG, and MRR metrics with benchmark-driven evaluation.
+- **`rationalevault memory search`** CLI subcommand.
+
+### Sprint I1–I2 — Memory Foundation & Intelligence
+- **Event Ledger**: Append-only event store with SQLite and PostgreSQL backends. Events carry project ID, stream ID, type, payload, metadata, and parent linkage.
+- **Event Schema**: Typed event system (`EventType` enum) covering all project lifecycle events.
+- **Memory Extraction**: Deterministic `MemoryRecord` derivation from events with SHA-256-based IDs (idempotent re-extraction).
+- **Memory Consolidation**: Duplicate cluster detection and consolidation candidate emission.
+- **Memory Intelligence**: Reference counting, recency tracking, lifecycle status management.
+- **Cognitive Head**: Append-only projection of agent task/decision/question state from the event stream.
+- **`rationalevault init`**, **`rationalevault memory`**, **`rationalevault doctor`** CLI subcommands.
+
+---
+
+## [0.1.0] — 2026-06-01 (Sprint A + B + D)
+
+### Initial Release
+- Event-sourced event store with SQLite backend.
+- Basic memory extraction and consolidation scaffold.
+- CLI initialization (`rationalevault init`) with YAML protocol, skill, and handoff checklist templates.
+- Platform adapter installation (`rationalevault install --platform claude|cursor|opencode|copilot`).
+- Docker PostgreSQL environment configuration.

rationalevault-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to RationaleVault
+
+Thank you for your interest in contributing to RationaleVault!
+
+---
+
+## Architecture Freeze Rules
+- We prioritize stability, documentation, and quality control.
+- No new runtime capabilities or schema extensions can be introduced without a formal proposal and consensus.
+
+## Setting Up Your Development Environment
+
+1. Clone the repository and navigate to the directory:
+   ```bash
+   git clone https://github.com/your-username/RationaleVault.git
+   cd RationaleVault
+   ```
+2. Create and activate a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+3. Install dependencies in editable mode:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+## Development Guidelines
+
+- **Write Unit Tests**: Every bug fix or change must include corresponding unit tests in the `tests/` directory.
+- **Run Quality Checks**:
+  Before submitting a PR, verify all components are fully functional:
+  ```bash
+  pytest
+  rationalevault doctor
+  rationalevault evaluate
+  ```
+- **central versioning**: Respect the centralized versioning schema in `rationalevault/__init__.py`.

rationalevault-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RationaleVault Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rationalevault-1.0.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: rationalevault
+Version: 1.0.0
+Summary: RationaleVault — Event-sourced cognitive continuity and memory layer for multi-agent AI workflows
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# RationaleVault (v1.0.0)
+
+**Event-sourced cognitive continuity and memory layer for multi-agent AI workflows.**
+
+RationaleVault enables any AI agent — Claude, OpenCode, ChatGPT, Cursor, Copilot — to resume work on a project with full context continuity, within 30 seconds, without manual summarization.
+
+---
+
+## Why RationaleVault Exists
+
+LLM agents lose context. As projects evolve over weeks or months, they accumulate decisions, lessons, failures, architectural constraints, and rationale. Standard RAG tools and vector databases fail to preserve these because they lack structural temporal order, resulting in context drift, memory duplication, and decision degradation.
+
+RationaleVault provides an event-sourced cognitive continuity layer. By treating events as the immutable source of truth and compiling memory, knowledge, and graphs as deterministic projections, RationaleVault ensures agents can reconstruct state and continue work with zero cognitive loss.
+
+## What RationaleVault Is Not
+
+To understand RationaleVault, it is helpful to clarify what it is not:
+- **Not a vector database**: RationaleVault uses structured keyword, domain, and profile-based slot allocation for deterministic context compilation.
+- **Not a graph database**: The knowledge graph in RationaleVault is a derived view (a projection), not a storage database.
+- **Not a workflow engine**: RationaleVault does not execute agent loops or handle tasks; it provides cognitive memory infrastructure.
+- **Not an agent framework**: RationaleVault is agent-agnostic and interfaces via standardized compiler adapters.
+- **Not a memory database**: RationaleVault is event-sourced; the immutable event ledger is the sole source of truth.
+
+---
+
+## Architecture Flow
+
+Every layer of RationaleVault has an implementation, evaluation metrics, and validation exit gates.
+
+```text
+Events (Ledger)
+      ↓
+Memory Extraction (Provenance / Deduplication)
+      ↓
+Memory Intelligence (Reference Counts / Recency)
+      ↓
+Retrieval Intelligence (Ranking & Keywords)
+      ↓
+Knowledge Synthesis (Synthesized Facts & Contradictions)
+      ↓
+Knowledge Evaluation (Density & Precision Gates)
+      ↓
+Knowledge Graph Projection (Nodes & Edge Integrity)
+      ↓
+Context Construction (Profile Slot Allocation Blending)
+      ↓
+Context Evaluation (Completeness & Traceability)
+      ↓
+Agent Compilers (Prompt Serialization / Adapters)
+      ↓
+Continuity Validation (Handoff Integrity Verification)
+```
+
+---
+
+## Quick Start
+
+### 1. Install RationaleVault
+
+Install RationaleVault in editable developer mode:
+```bash
+pip install -e ".[dev]"
+```
+
+### 2. Verify Installation
+
+Run the system diagnostics tool to verify that the environment, active databases, registry, and projection chains are fully functional:
+```bash
+rationalevault doctor
+```
+
+### 3. Run the Unified Evaluation Suite
+
+Execute the full evaluation pipeline, checking all exit gates (Memory, Knowledge, Context, Compilers, Continuity, Graph, and Examples):
+```bash
+rationalevault evaluate
+```
+
+This generates a PEP 440-compliant release manifest at `.rationalevault/reports/release_manifest.json` and a markdown summary at `.rationalevault/reports/report.md`.
+
+### 4. Run tests
+```bash
+pytest
+```
+All 283 tests will run (269 pass; 14 are skipped as they require a live PostgreSQL database connection).
+
+---
+
+## Design Principles
+- **Ledger Invariance**: `event_sequence` is the only authoritative ordering key.
+- **Determinism**: Same events always project to the identical memory, knowledge, and graph states.
+- **Provenance Traceability**: Every context citation must trace back to original event ledger records.
+- **Zero-Dependency Core**: Standard configuration runs local-first on SQLite with zero external database setup.

rationalevault-1.0.0/README.md

@@ -0,0 +1,93 @@
+# RationaleVault (v1.0.0)
+
+**Event-sourced cognitive continuity and memory layer for multi-agent AI workflows.**
+
+RationaleVault enables any AI agent — Claude, OpenCode, ChatGPT, Cursor, Copilot — to resume work on a project with full context continuity, within 30 seconds, without manual summarization.
+
+---
+
+## Why RationaleVault Exists
+
+LLM agents lose context. As projects evolve over weeks or months, they accumulate decisions, lessons, failures, architectural constraints, and rationale. Standard RAG tools and vector databases fail to preserve these because they lack structural temporal order, resulting in context drift, memory duplication, and decision degradation.
+
+RationaleVault provides an event-sourced cognitive continuity layer. By treating events as the immutable source of truth and compiling memory, knowledge, and graphs as deterministic projections, RationaleVault ensures agents can reconstruct state and continue work with zero cognitive loss.
+
+## What RationaleVault Is Not
+
+To understand RationaleVault, it is helpful to clarify what it is not:
+- **Not a vector database**: RationaleVault uses structured keyword, domain, and profile-based slot allocation for deterministic context compilation.
+- **Not a graph database**: The knowledge graph in RationaleVault is a derived view (a projection), not a storage database.
+- **Not a workflow engine**: RationaleVault does not execute agent loops or handle tasks; it provides cognitive memory infrastructure.
+- **Not an agent framework**: RationaleVault is agent-agnostic and interfaces via standardized compiler adapters.
+- **Not a memory database**: RationaleVault is event-sourced; the immutable event ledger is the sole source of truth.
+
+---
+
+## Architecture Flow
+
+Every layer of RationaleVault has an implementation, evaluation metrics, and validation exit gates.
+
+```text
+Events (Ledger)
+      ↓
+Memory Extraction (Provenance / Deduplication)
+      ↓
+Memory Intelligence (Reference Counts / Recency)
+      ↓
+Retrieval Intelligence (Ranking & Keywords)
+      ↓
+Knowledge Synthesis (Synthesized Facts & Contradictions)
+      ↓
+Knowledge Evaluation (Density & Precision Gates)
+      ↓
+Knowledge Graph Projection (Nodes & Edge Integrity)
+      ↓
+Context Construction (Profile Slot Allocation Blending)
+      ↓
+Context Evaluation (Completeness & Traceability)
+      ↓
+Agent Compilers (Prompt Serialization / Adapters)
+      ↓
+Continuity Validation (Handoff Integrity Verification)
+```
+
+---
+
+## Quick Start
+
+### 1. Install RationaleVault
+
+Install RationaleVault in editable developer mode:
+```bash
+pip install -e ".[dev]"
+```
+
+### 2. Verify Installation
+
+Run the system diagnostics tool to verify that the environment, active databases, registry, and projection chains are fully functional:
+```bash
+rationalevault doctor
+```
+
+### 3. Run the Unified Evaluation Suite
+
+Execute the full evaluation pipeline, checking all exit gates (Memory, Knowledge, Context, Compilers, Continuity, Graph, and Examples):
+```bash
+rationalevault evaluate
+```
+
+This generates a PEP 440-compliant release manifest at `.rationalevault/reports/release_manifest.json` and a markdown summary at `.rationalevault/reports/report.md`.
+
+### 4. Run tests
+```bash
+pytest
+```
+All 283 tests will run (269 pass; 14 are skipped as they require a live PostgreSQL database connection).
+
+---
+
+## Design Principles
+- **Ledger Invariance**: `event_sequence` is the only authoritative ordering key.
+- **Determinism**: Same events always project to the identical memory, knowledge, and graph states.
+- **Provenance Traceability**: Every context citation must trace back to original event ledger records.
+- **Zero-Dependency Core**: Standard configuration runs local-first on SQLite with zero external database setup.

rationalevault-1.0.0/SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest release versions of RationaleVault are supported with security updates.
+
+| Version | Supported |
+| --- | --- |
+| 1.0.x | :white_check_mark: |
+| < 1.0.0 | :x: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in RationaleVault, please do **not** open a public issue. Instead, report the vulnerability by emailing the maintainers directly at security@example.com.
+
+We will acknowledge receipt of your vulnerability report within 48 hours and work with you to resolve the issue before releasing details publicly.

rationalevault-1.0.0/docker/postgres/docker-compose.yml

@@ -0,0 +1,23 @@
+services:
+  postgres:
+    image: postgres:17
+    container_name: relay_postgres
+    environment:
+      POSTGRES_DB: relay
+      POSTGRES_USER: relay
+      POSTGRES_PASSWORD: relay
+    ports:
+      - "5432:5432"
+    volumes:
+      - relay_postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U relay -d relay"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 10s
+    restart: unless-stopped
+
+volumes:
+  relay_postgres_data:
+    name: relay_postgres_data