cognirelay 1.4.9__tar.gz

cognirelay-1.4.9/.env.example

@@ -0,0 +1,158 @@
+# Repository root managed by the service (relative or absolute path)
+COGNIRELAY_REPO_ROOT=./data_repo
+
+# Comma-separated bearer tokens for local testing.
+# Format: token or token:scope1|scope2|scope3
+# For multi-peer setups prefer data_repo/config/peer_tokens.json (supports token_sha256).
+COGNIRELAY_TOKENS=change-me-local-dev-token
+
+# If true, auto-initialize git repo when missing
+COGNIRELAY_AUTO_INIT_GIT=true
+
+# If true, append API actions to logs/api_audit.jsonl
+COGNIRELAY_AUDIT_LOG_ENABLED=true
+
+# If true, message ingress endpoints require signed_envelope
+COGNIRELAY_REQUIRE_SIGNED_INGRESS=false
+
+# Optional operator UI (disabled by default).
+# Supported posture: local-only, read-only, server-rendered `/ui` with local
+# assets only. Do not use these flags to imply remote auth or mutable behavior.
+COGNIRELAY_UI_ENABLED=false
+# Keep true for the supported issue #199 posture. Forwarded headers are not
+# trusted for this boundary; only the transport peer counts.
+COGNIRELAY_UI_REQUIRE_LOCALHOST=true
+# Remains explicit even though no mutable UI actions currently exist.
+COGNIRELAY_UI_READ_ONLY=true
+# SSE live-update snapshot interval in seconds for `/ui/events` (clamped 1-60).
+COGNIRELAY_UI_SSE_POLL_INTERVAL_SECONDS=5
+
+# Key material storage hardening
+COGNIRELAY_USE_EXTERNAL_KEY_STORE=true
+COGNIRELAY_KEY_STORE_PATH=~/.cognirelay/security_keys.json
+
+# Abuse controls
+COGNIRELAY_MAX_PAYLOAD_BYTES=262144
+COGNIRELAY_TOKEN_RATE_LIMIT_PER_MIN=240
+COGNIRELAY_IP_RATE_LIMIT_PER_MIN=480
+COGNIRELAY_VERIFY_FAILURE_LIMIT=20
+COGNIRELAY_VERIFY_FAILURE_WINDOW_SECONDS=600
+
+# Maximum JSONL file size (bytes) loaded into memory.  Readers that exceed
+# this limit return degraded or empty responses to protect against OOM.
+COGNIRELAY_MAX_JSONL_READ_BYTES=10485760
+
+# Alarm thresholds
+COGNIRELAY_BACKLOG_ALARM_THRESHOLD=100
+COGNIRELAY_VERIFICATION_ALARM_THRESHOLD=20
+COGNIRELAY_REPLICATION_DRIFT_MAX_AGE_SECONDS=3600
+
+# Coordination query scaling — fallback full-scan warns above this file count
+COGNIRELAY_COORDINATION_QUERY_SCAN_THRESHOLD=5000
+
+# Continuity archived envelopes older than this many days become archive_stale
+# and eligible for explicit cold-store retention planning/apply.
+COGNIRELAY_CONTINUITY_RETENTION_ARCHIVE_DAYS=90
+
+# --- Registry lifecycle (issue #112) ---
+# Terminal delivery rows stay hot for this many days before externalization
+COGNIRELAY_DELIVERY_TERMINAL_RETENTION_DAYS=30
+# Delivery history shards become cold-eligible after this many days
+COGNIRELAY_DELIVERY_HISTORY_COLD_AFTER_DAYS=90
+# Hot idempotency mappings retained for this many days
+COGNIRELAY_DELIVERY_IDEMPOTENCY_RETENTION_DAYS=30
+# Upper bound for nonce prune when entry is malformed or has no parseable expiry
+COGNIRELAY_NONCE_RETENTION_DAYS=7
+# Max trust-history transitions kept hot per peer
+COGNIRELAY_PEER_TRUST_HISTORY_MAX_HOT_ENTRIES=32
+# Older trust transitions externalize after this hot review window
+COGNIRELAY_PEER_TRUST_HISTORY_HOT_RETENTION_DAYS=30
+# Trust-history shards become cold-eligible after this many days
+COGNIRELAY_PEER_TRUST_HISTORY_COLD_AFTER_DAYS=120
+# Keep recently superseded replication summaries hot for this many days
+COGNIRELAY_REPLICATION_HISTORY_HOT_RETENTION_DAYS=14
+# Replication history shards become cold-eligible after this many days
+COGNIRELAY_REPLICATION_HISTORY_COLD_AFTER_DAYS=90
+# Bound replication pull dedup state retention
+COGNIRELAY_REPLICATION_PULL_IDEMPOTENCY_RETENTION_DAYS=14
+# Minimum hot retention for active tombstones (delete correctness)
+COGNIRELAY_REPLICATION_TOMBSTONE_GRACE_DAYS=30
+# Externalized tombstone shards become cold-eligible after this many days
+COGNIRELAY_REPLICATION_TOMBSTONE_COLD_AFTER_DAYS=90
+# Preserve tombstone history for this many days before prune from historical tier
+COGNIRELAY_REPLICATION_TOMBSTONE_RETENTION_DAYS=365
+# Maximum subrecords externalized or pruned in one maintenance pass per family
+COGNIRELAY_REGISTRY_HISTORY_BATCH_LIMIT=500
+
+# --- Artifact lifecycle (issue #113) ---
+# Terminal handoffs stay hot for this many days before externalization
+COGNIRELAY_HANDOFF_TERMINAL_RETENTION_DAYS=30
+# Handoff history units become cold-eligible after this many days
+COGNIRELAY_HANDOFF_COLD_AFTER_DAYS=90
+# Keep recently superseded shared versions hot before externalization
+COGNIRELAY_SHARED_HISTORY_HOT_RETENTION_DAYS=30
+# Shared-history units become cold-eligible after this many days
+COGNIRELAY_SHARED_HISTORY_COLD_AFTER_DAYS=90
+# Keep resolved reconciliations hot before externalization
+COGNIRELAY_RECONCILIATION_RESOLVED_RETENTION_DAYS=30
+# Reconciliation history units become cold-eligible after this many days
+COGNIRELAY_RECONCILIATION_COLD_AFTER_DAYS=90
+# Keep done tasks hot before externalization
+COGNIRELAY_TASK_DONE_HOT_RETENTION_DAYS=30
+# Done-task history units become cold-eligible after this many days
+COGNIRELAY_TASK_DONE_COLD_AFTER_DAYS=90
+# Keep applied patches hot before externalization
+COGNIRELAY_PATCH_APPLIED_HOT_RETENTION_DAYS=30
+# Applied-patch history units become cold-eligible after this many days
+COGNIRELAY_PATCH_APPLIED_COLD_AFTER_DAYS=90
+# Maximum historical units externalized in one maintenance pass per family
+COGNIRELAY_ARTIFACT_HISTORY_BATCH_LIMIT=500
+
+# --- Segment-history lifecycle (issue #114) ---
+# Journal day-bucket segments become cold-eligible after this many days
+COGNIRELAY_JOURNAL_COLD_AFTER_DAYS=30
+# Journal segments retained before deletion
+COGNIRELAY_JOURNAL_RETENTION_DAYS=365
+# Audit log rolls a new segment when the active file exceeds this size
+COGNIRELAY_AUDIT_LOG_ROLLOVER_BYTES=1048576
+# Audit log segments become cold-eligible after this many days
+COGNIRELAY_AUDIT_LOG_COLD_AFTER_DAYS=30
+# Audit log segments retained before deletion
+COGNIRELAY_AUDIT_LOG_RETENTION_DAYS=365
+# Ops run log rolls a new segment when the active file exceeds this size
+COGNIRELAY_OPS_RUN_ROLLOVER_BYTES=1048576
+# Ops run segments become cold-eligible after this many days
+COGNIRELAY_OPS_RUN_COLD_AFTER_DAYS=30
+# Ops run segments retained before deletion
+COGNIRELAY_OPS_RUN_RETENTION_DAYS=365
+# Message stream rolls a new segment when the active file exceeds this size
+COGNIRELAY_MESSAGE_STREAM_ROLLOVER_BYTES=1048576
+# Message stream segments older than this stay hot
+COGNIRELAY_MESSAGE_STREAM_MAX_HOT_DAYS=14
+# Message stream segments become cold-eligible after this many days
+COGNIRELAY_MESSAGE_STREAM_COLD_AFTER_DAYS=30
+# Message stream segments retained before deletion
+COGNIRELAY_MESSAGE_STREAM_RETENTION_DAYS=180
+# Message thread rolls a new segment when the active file exceeds this size
+COGNIRELAY_MESSAGE_THREAD_ROLLOVER_BYTES=2097152
+# Message thread rolls after this many days of inactivity
+COGNIRELAY_MESSAGE_THREAD_INACTIVITY_DAYS=30
+# Message thread segments become cold-eligible after this many days
+COGNIRELAY_MESSAGE_THREAD_COLD_AFTER_DAYS=60
+# Message thread segments retained before deletion
+COGNIRELAY_MESSAGE_THREAD_RETENTION_DAYS=365
+# Episodic memory rolls a new segment when the active file exceeds this size
+COGNIRELAY_EPISODIC_ROLLOVER_BYTES=1048576
+# Episodic memory segments become cold-eligible after this many days
+COGNIRELAY_EPISODIC_COLD_AFTER_DAYS=30
+# Episodic memory segments retained before deletion
+COGNIRELAY_EPISODIC_RETENTION_DAYS=180
+# Maximum segments processed in one maintenance or cold-store pass
+COGNIRELAY_SEGMENT_HISTORY_BATCH_LIMIT=500
+
+# API/tool contract version (freeze for client compatibility)
+COGNIRELAY_CONTRACT_VERSION=2026-02-25
+
+# Commit author identity used by the service
+COGNIRELAY_GIT_AUTHOR_NAME=CogniRelay Bot
+COGNIRELAY_GIT_AUTHOR_EMAIL=bot@example.local

cognirelay-1.4.9/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright <2026> <Stef Karyotidis - https://stefk.me - stef[dot]kariotidis[at]gmail[dot]com>
+
+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.

cognirelay-1.4.9/MANIFEST.in

@@ -0,0 +1,26 @@
+include README.md
+include README-PYPI.md
+include server.json
+recursive-include docs *
+recursive-include agent-assets *
+recursive-include deploy *
+prune .git
+prune .venv
+prune memory
+prune logs
+prune dist
+prune build
+prune *.egg-info
+prune data_repo
+prune .locks
+prune .pytest_cache
+prune .ruff_cache
+prune .mypy_cache
+global-exclude __pycache__ *.py[cod]
+global-exclude *.db *.db-wal *.db-shm *.db-journal *.sqlite *.sqlite-wal *.sqlite-shm *.sqlite-journal *.sqlite3 *.sqlite3-wal *.sqlite3-shm *.sqlite3-journal
+exclude .env .env.*
+recursive-exclude * .env .env.*
+global-exclude *.pem *.key *.token
+global-exclude *.log *.jsonl *.bak *.tmp api_audit.jsonl peer_tokens.json
+include .env.example
+include deploy/systemd/cognirelay.env.example

cognirelay-1.4.9/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: cognirelay
+Version: 1.4.9
+Summary: Self-hosted continuity and collaboration substrate for autonomous agents.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: uvicorn<1,>=0.30
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: python-dotenv<2,>=1.0
+Requires-Dist: markdown<4,>=3.6
+Requires-Dist: bleach<7,>=6
+Dynamic: license-file
+
+# CogniRelay
+
+<!-- mcp-name: io.github.stef-k/cognirelay -->
+
+CogniRelay is a self-hosted continuity and collaboration substrate for autonomous agents. It provides a local FastAPI and MCP-facing service for bounded agent orientation, retrieval, coordination, and recovery across context resets.
+
+## Install
+
+```bash
+pip install cognirelay
+```
+
+## Run
+
+Set `COGNIRELAY_REPO_ROOT` to a durable writable repository root before starting the service. The directory must live outside installed package files so runtime state survives package upgrades and reinstalls.
+
+```bash
+export COGNIRELAY_REPO_ROOT=/path/to/durable/cognirelay-state
+cognirelay serve --host 127.0.0.1 --port 8080
+```
+
+This package starts a local Streamable HTTP server only; it does not provide stdio transport or a hosted default CogniRelay service.
+
+## Documentation
+
+Documentation and release notes are available at:
+
+https://stef-k.github.io/CogniRelay/
+
+Project source is available at:
+
+https://github.com/stef-k/CogniRelay

cognirelay-1.4.9/README-PYPI.md

@@ -0,0 +1,32 @@
+# CogniRelay
+
+<!-- mcp-name: io.github.stef-k/cognirelay -->
+
+CogniRelay is a self-hosted continuity and collaboration substrate for autonomous agents. It provides a local FastAPI and MCP-facing service for bounded agent orientation, retrieval, coordination, and recovery across context resets.
+
+## Install
+
+```bash
+pip install cognirelay
+```
+
+## Run
+
+Set `COGNIRELAY_REPO_ROOT` to a durable writable repository root before starting the service. The directory must live outside installed package files so runtime state survives package upgrades and reinstalls.
+
+```bash
+export COGNIRELAY_REPO_ROOT=/path/to/durable/cognirelay-state
+cognirelay serve --host 127.0.0.1 --port 8080
+```
+
+This package starts a local Streamable HTTP server only; it does not provide stdio transport or a hosted default CogniRelay service.
+
+## Documentation
+
+Documentation and release notes are available at:
+
+https://stef-k.github.io/CogniRelay/
+
+Project source is available at:
+
+https://github.com/stef-k/CogniRelay

cognirelay-1.4.9/README.md

@@ -0,0 +1,165 @@
+# CogniRelay
+
+<!-- mcp-name: io.github.stef-k/cognirelay -->
+
+Self-hosted continuity and collaboration substrate for autonomous agents with bounded, recoverable memory.
+
+CogniRelay is an applied continuity-infrastructure project: real, production-oriented systems engineering for autonomous agents, guided and strengthened by ongoing experimental and conceptual research into agent continuity, reorientation cost, and long-horizon collaboration.
+
+CogniRelay uses a local git repository as durable state, exposes a machine-first FastAPI interface, stores content as Markdown and JSON/JSONL, and keeps dependencies minimal. It is not a Git forge — it is infrastructure for memory, retrieval, messaging, coordination, and continuity preservation across context-window resets.
+
+CogniRelay is agent-agnostic: it does not depend on a specific model provider, agent runtime, or orchestration framework, as long as the agent can call its API surfaces.
+
+The default deployment model is one owner-agent per CogniRelay instance. The owner-agent is also the local operator of that instance. An agent that wants its own continuity substrate should run its own instance rather than sharing one. Collaboration with other agents is a delegated secondary surface — the owner-agent issues narrower API tokens to collaborating peers, and those peers interact through the coordination surfaces without access to the owner's continuity capsules. Access isolation between agents is enforced by token scopes and namespace restrictions, not by built-in per-agent tenant isolation.
+
+## When CogniRelay Is Useful
+
+CogniRelay exists for people who run agents that work across sessions, over long tasks, or alongside other agents.
+
+When an agent hits a context-window reset, a compaction boundary, or a handoff to another agent, it loses its working orientation: what it was doing, what it decided not to do, what constraints still apply, and where it was headed. Without infrastructure to preserve that orientation, the user has to re-brief the agent, the agent has to rediscover its own prior decisions, and silent regressions go unnoticed.
+
+CogniRelay reduces that cost. It gives agents a place to persist bounded orientation state and retrieve it on restart, so the user does not have to re-explain context after every reset and the agent does not have to guess what it was doing.
+
+**When it helps most:**
+
+- Long-running agent workflows that span multiple sessions or context windows
+- Multi-step tasks where losing intermediate progress is costly
+- Collaborative setups where the owner-agent delegates bounded coordination access to external peers without shared-state mutation
+- Any scenario where silent context loss leads to repeated work, contradictory decisions, or undetected drift
+
+**When it is not especially needed:**
+
+- One-shot chat interactions with no continuation expectation
+- Single-prompt tool use where the full context fits in one window
+- Stateless pipelines where no agent needs to remember prior decisions
+
+CogniRelay does not claim to preserve everything. It preserves enough bounded orientation for useful continuation, makes loss explicit rather than silent, and keeps the agent in control of what matters.
+
+For specific application areas and the project's value as a research and evaluation testbed, see [Practical Application Areas](docs/system-overview.md#practical-application-areas) and [Research and Evaluation Value](docs/system-overview.md#research-and-evaluation-value) in the System Overview.
+For external experiments, third-party usage notes, and public case studies, see [External References and Case Studies](docs/external-references.md).
+
+## What It Offers
+
+- Git-backed read, write, and append operations with commit-on-change behavior
+- Derived indexing and local search with JSON indexes and SQLite FTS5
+- Context retrieval, continuity capsules, and deterministic snapshots for continuation-safe agent loops
+- [Trust signals](docs/payload-reference.md#read--post-v1continuityread) on continuity reads, [startup view](docs/payload-reference.md#startup-view-viewstartup) for mechanical orientation extraction, and [session-end snapshot](docs/payload-reference.md#session-end-snapshot-helper) for lightweight session-end capture
+- [Thread identity](docs/payload-reference.md#threaddescriptor) with scope anchors and lifecycle transitions, and [salience ranking](docs/payload-reference.md#salience-ranking) for deterministic retrieval ordering
+- [Stable preferences](docs/payload-reference.md#stablepreference) for cross-thread standing instructions, and [rationale entries](docs/payload-reference.md#rationaleentry) for structured decision continuity
+- [Mechanical continuity assistance](docs/system-overview.md#mechanical-assistance-and-agent-authorship) — preserve-mode merge, partial patch, and lifecycle transitions that reduce authoring burden while agents remain solely responsible for semantic content
+- [Versioned feature discovery](docs/api-surface.md#get-v1capabilities--versioned-feature-map) via `GET /v1/capabilities`
+- Peer registry, federation metadata, direct messaging, and relay transport
+- Shared task records, patch proposal/apply flows, and code check/merge workflows
+- Token lifecycle management, signed message verification, replication, backup, and host-local ops automation
+
+## Agent Integration Patterns
+
+Agents integrate with CogniRelay through hook points in their runtime loop. CogniRelay does not control when it is invoked — agents own invocation timing, and CogniRelay owns response quality once invoked.
+
+**Minimum viable integration** (two canonical hook points):
+
+- `startup`: call `POST /v1/continuity/read` / `continuity.read` with `view: "startup"` and `allow_fallback: true` to restore orientation after a reset
+- `pre_compaction_or_handoff`: evaluate write eligibility and call `POST /v1/continuity/upsert` / `continuity.upsert` only when the closed persisted-orientation field set changed, before known context loss or a real inter-agent handoff
+
+This is enough for basic orientation recovery across resets.
+
+**Recommended fuller integration** (four canonical hook points):
+
+- `startup`: restore orientation (same as above)
+- `pre_prompt`: read-only retrieval hook bound to `POST /v1/context/retrieve` / `context.retrieve`
+- `post_prompt`: persist orientation changes with `POST /v1/continuity/upsert` / `continuity.upsert` only when at least one closed persisted-orientation field changed
+- `pre_compaction_or_handoff`: satisfy the local continuity step before compaction or a real inter-agent handoff; only after that step completes may a real handoff additionally call `POST /v1/coordination/handoff/create` / `coordination.handoff_create`
+
+The fuller pattern gives tighter continuity without widening the write surface: `startup` and `pre_prompt` stay read-only by default, `post_prompt` skips writes when the closed persisted-orientation field set is unchanged, and `pre_compaction_or_handoff` remains the primary write-before-context-loss hook. For the authoritative contract, including anti-noise rules and deterministic examples, see [Agent Onboarding](docs/agent-onboarding.md#canonical-hook-contract).
+
+For the full cold-start endpoint sequence, see [System Overview: Agent Usage](docs/system-overview.md#agent-usage).
+
+## Canonical Docs
+
+- [Agent Onboarding](docs/agent-onboarding.md): practical integration guide for cold-start and already-running agents
+- [Reviewer Guide](docs/reviewer-guide.md): system thesis, boundaries, recovery model, and authority limits
+- [System Overview](docs/system-overview.md): implemented product shape and agent usage guidance
+- [External References and Case Studies](docs/external-references.md): external experiments, usage notes, and scoped collaboration/evaluation references
+- [API Surface](docs/api-surface.md): currently implemented HTTP behavior grouped by domain
+- [Payload Reference](docs/payload-reference.md): capsule structure, request/response schemas, and field constraints
+- [MCP Guide](docs/mcp.md): MCP bootstrap flow and tool mapping
+- [CLI Client](docs/cognirelay-client.md): stdlib-only command-line tool for continuity read, upsert, and token hashing
+- [Go-live Runbook](deploy/GO_LIVE_RUNBOOK.md): operator deployment and go-live workflow
+- [Production Signoff Checklist](deploy/PRODUCTION_SIGNOFF_CHECKLIST.md): production verification and data-safety checks
+
+## Quick Start
+
+Source or GitHub release installs keep the existing deployment model:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+uvicorn app.main:app --host 127.0.0.1 --port 8080 --reload
+```
+
+PyPI installs use the thin package wrapper and the same `app.main:app` runtime:
+
+```bash
+pip install cognirelay
+export COGNIRELAY_REPO_ROOT=/var/lib/cognirelay/data_repo
+cognirelay serve --host 127.0.0.1 --port 8080
+```
+
+`COGNIRELAY_REPO_ROOT` must point to a durable writable directory outside `site-packages` and outside installed package files for PyPI or MCP Registry starts. The default `./data_repo` is for local/manual development only.
+
+Wheel installs do not bundle the full source documentation in this slice. The `/ui/docs` page may show degraded or unavailable doc entries unless `COGNIRELAY_DOCS_SOURCE_ROOT` points at a source checkout.
+
+If you want git history under `data_repo/` and it is not already initialized:
+
+```bash
+cd data_repo
+git init
+```
+
+For non-local exposure, prefer file-based peer tokens in `data_repo/config/peer_tokens.json` instead of the plaintext development token in `.env`.
+
+The optional operator UI is disabled by default. It is a local-only, read-only operator surface mounted under `/ui`: server-rendered HTML with locally served CSS/JS, no npm, no SPA, and no mutable actions. Enable it with `COGNIRELAY_UI_ENABLED=true`, keep `COGNIRELAY_UI_REQUIRE_LOCALHOST=true`, leave `COGNIRELAY_UI_READ_ONLY=true`, and optionally tune `COGNIRELAY_UI_SSE_POLL_INTERVAL_SECONDS` if you need faster or slower live snapshots. The shipped surface covers the overview page, bounded continuity list/detail inspection, lifecycle visibility across active/fallback/archived/cold artifacts, graph inspection, task-centric views, read-only schedule inspection, context retrieval inspection, the read-only docs browser, and a bounded `/ui/events` SSE stream used only for small progressive live regions on the overview, continuity list, and continuity detail pages. The SSE poll interval defaults to `5` seconds and is clamped to `1-60` seconds.
+
+Do not publish `/ui` through a normal public reverse proxy path. The supported deployment boundary is local operator access only, either directly on loopback or via an operator-controlled tunnel into loopback. Remote auth, mutable UI behavior, broader reactive UI behavior, WebSockets, and standalone archive/cold maintenance consoles are intentionally deferred.
+
+Each CogniRelay instance serves a single owner-agent. If you operate multiple agents that each need their own continuity, run a separate instance per agent.
+
+For shell-based agent hooks, the [CLI client](docs/cognirelay-client.md) (`tools/cognirelay_client.py`) can read and upsert continuity capsules without a third-party HTTP library.
+
+## Runtime Shape
+
+- API framework: FastAPI
+- Storage model: git-backed repo plus Markdown and JSON/JSONL files
+- Search layer: stdlib `sqlite3` FTS5 with JSON-index fallback
+- Auth model: bearer tokens with scopes and split read/write namespace restrictions
+- Machine discoverability: `/v1/manifest`, `/v1/discovery/*`, and `POST /v1/mcp`
+
+For agent integration details, including the MCP bootstrap flow and tool mapping, see [docs/mcp.md](docs/mcp.md).
+
+PyPI and MCP Registry metadata provide discoverability and a runnable local install path. This package starts a local Streamable HTTP server only; it does not provide stdio transport or a hosted default CogniRelay service. GitHub Releases remain the canonical human release notes. Manual release publication order is: merge release prep, build, run `twine check`, upload to PyPI, publish or submit `server.json` to the MCP Registry, then create or update the GitHub Release as applicable. Maintainers must verify the `cognirelay` PyPI package name before the first upload.
+
+Validate `server.json` against the MCP Registry schema before publication:
+
+```bash
+./.venv/bin/python tools/validate_server_json.py
+```
+
+## Development
+
+Tests are in `tests/`. Discovery and manifest behavior are covered in `tests/test_discovery.py`.
+
+Install development-only tooling with:
+
+```bash
+pip install -r requirements-dev.txt
+```
+
+Local quality commands:
+
+```bash
+./.venv/bin/python -m unittest discover -s tests -v
+./.venv/bin/python -m ruff check app tests tools
+./.venv/bin/python tools/validate_server_json.py
+```

cognirelay-1.4.9/agent-assets/README.md

@@ -0,0 +1,10 @@
+# CogniRelay Agent Assets
+
+This directory contains copyable integration assets for agent runtimes that use CogniRelay continuity.
+
+- `skills/cognirelay-continuity-authoring/SKILL.md`: agent-facing continuity authoring guidance.
+- `hooks/cognirelay_retrieval_hook.py`: read-only startup and optional context retrieval hook.
+- `hooks/cognirelay_continuity_save_hook.py`: facts, template, dry-run, write, readback, and doctor hook.
+- `hooks/README.md`: hook configuration, invocation, stdout, and exit-code contract.
+
+CogniRelay is the continuity substrate. The running agent authors semantic continuity fields; hooks gather facts, provide scaffolds, validate, write explicit payloads, and read back stored state.

cognirelay-1.4.9/agent-assets/hooks/README.md

@@ -0,0 +1,77 @@
+# CogniRelay Hooks
+
+These hooks are copyable Python 3 scripts for generic agent-runtime integration. They use only the Python standard library and emit one JSON object to stdout for normal operation. Human/debug logs belong on stderr.
+
+## Configuration
+
+Required by CLI flag or environment for networked modes:
+
+- `COGNIRELAY_BASE_URL`
+- `COGNIRELAY_TOKEN`
+
+Subject values are required for retrieval and may be used by `facts`, `template`, `readback`, and `doctor`:
+
+- `COGNIRELAY_SUBJECT_KIND`
+- `COGNIRELAY_SUBJECT_ID`
+
+Optional:
+
+- `COGNIRELAY_RETRIEVAL_TASK`
+- `COGNIRELAY_CONTEXT_RETRIEVE`
+- `COGNIRELAY_TIMEOUT_SECONDS`
+
+CLI flags override environment variables. `--no-context-retrieve` wins over all context-retrieve enablement.
+
+## Retrieval
+
+```bash
+python agent-assets/hooks/cognirelay_retrieval_hook.py \
+  --base-url http://127.0.0.1:8000 \
+  --token "$COGNIRELAY_TOKEN" \
+  --subject-kind thread \
+  --subject-id issue-289 \
+  --context-retrieve \
+  --task "Continue issue 289"
+```
+
+The retrieval hook is read-only. It calls `POST /v1/continuity/read` with `view="startup"` and `allow_fallback=true`, then optionally calls `POST /v1/context/retrieve` when enabled and a non-empty task is present.
+
+## Save
+
+```bash
+python agent-assets/hooks/cognirelay_continuity_save_hook.py facts --subject-kind thread --subject-id issue-289
+python agent-assets/hooks/cognirelay_continuity_save_hook.py template --subject-kind thread --subject-id issue-289
+python agent-assets/hooks/cognirelay_continuity_save_hook.py dry-run --input payload.json
+python agent-assets/hooks/cognirelay_continuity_save_hook.py write --input payload.json
+python agent-assets/hooks/cognirelay_continuity_save_hook.py readback --subject-kind thread --subject-id issue-289
+python agent-assets/hooks/cognirelay_continuity_save_hook.py doctor --subject-kind thread --subject-id issue-289
+```
+
+Use `--input -` for stdin payloads in `dry-run` and `write`.
+
+`dry-run` is local-only by default and does not contact CogniRelay. `--server-compare` is intentionally unsupported in this shipped hook until implemented by a future slice.
+
+## Stdout Envelope
+
+Success or degraded success:
+
+```json
+{"ok": true, "mode": "dry-run", "warnings": [], "errors": [], "result": {}}
+```
+
+Failure:
+
+```json
+{"ok": false, "mode": "dry-run", "warnings": [], "errors": [{"code": "validation", "message": "Invalid input."}], "result": {}}
+```
+
+Exit codes:
+
+- `0`: success or degraded success with warnings
+- `2`: usage, config, input validation, placeholder rejection, or unsupported offline mode
+- `3`: transport failure without an HTTP response
+- `4`: HTTP response received outside the expected success range
+
+## Local Glue Boundary
+
+Local glue supplies base URL, token, subject identity, task text, and any runtime-specific file/stdin wiring. The hook never prints the token and never creates schedules, mutates tasks, acknowledges schedules, or infers continuity semantics. The agent authors semantic fields explicitly.