context-bridge-memory 0.1.0__tar.gz

context_bridge_memory-0.1.0/.dockerignore

@@ -0,0 +1,20 @@
+.git
+.github
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+.ruff_cache
+.coverage
+htmlcov
+tests
+*.db
+*.sqlite3
+.env
+qdrant_storage
+.fastembed_cache
+docker-compose.yml
+Dockerfile
+.dockerignore

context_bridge_memory-0.1.0/.env.example

@@ -0,0 +1,127 @@
+# --- API ---
+API_HOST=0.0.0.0
+API_PORT=8000
+LOG_LEVEL=info
+
+# --- Security ---
+# Comma-separated API keys sent via the X-API-Key header. Empty = auth disabled.
+API_KEYS=
+# Optional per-key namespace allow-list as JSON. "*" or omission = all namespaces.
+# Example: {"team-a-key": ["team-a"], "ops-key": ["*"]}
+API_KEY_NAMESPACES=
+# Optional RBAC policies (namespace globs + read/write permissions) as JSON.
+# Example: {"reader": {"namespaces": ["team-a*"], "permissions": ["read"]}}
+API_KEY_POLICIES=
+# Per-identity requests per minute on data-plane routes. 0 = limiter disabled.
+RATE_LIMIT_PER_MINUTE=0
+# Rate limiter backend: "memory" (single replica) or "redis" (shared/horizontal).
+RATE_LIMIT_BACKEND=memory
+# CORS allowed origins (comma-separated, or "*").
+CORS_ALLOW_ORIGINS=*
+
+# --- Observability ---
+# Expose Prometheus metrics at /metrics and record request latency.
+METRICS_ENABLED=true
+# OpenTelemetry tracing (requires the 'otel' extra). Exports spans via OTLP.
+TRACING_ENABLED=false
+OTEL_SERVICE_NAME=context-bridge
+OTEL_EXPORTER_OTLP_ENDPOINT=
+
+# --- Vector store (Qdrant) ---
+# Use ":memory:" for an ephemeral in-process store (great for local dev / tests),
+# or a URL such as http://localhost:6333 for a running Qdrant instance.
+QDRANT_URL=:memory:
+QDRANT_API_KEY=
+QDRANT_COLLECTION=context_bridge
+
+# --- Embeddings ---
+# Provider: "hashing" (offline), "fastembed" (local), "openai", or "cohere".
+EMBED_PROVIDER=hashing
+EMBED_DENSE_MODEL=BAAI/bge-small-en-v1.5
+EMBED_SPARSE_MODEL=Qdrant/bm25
+EMBED_DIM=384
+
+# External provider credentials (used by EMBED_PROVIDER/RERANK_PROVIDER openai|cohere)
+OPENAI_API_KEY=
+OPENAI_BASE_URL=
+COHERE_API_KEY=
+
+# --- Reranker ---
+# Provider: "identity" (no-op, keeps fusion order) or "fastembed".
+RERANK_PROVIDER=identity
+RERANK_MODEL=Xenova/ms-marco-MiniLM-L-6-v2
+
+# --- Summarizer ---
+# Provider: "extractive" (no model) or "llm" (OpenAI-compatible chat endpoint;
+# falls back to extractive on error). Works with any local/self-hosted server.
+SUMMARIZER_PROVIDER=extractive
+LLM_BASE_URL=http://localhost:11434/v1
+LLM_API_KEY=
+LLM_MODEL=qwen2.5
+LLM_TIMEOUT=30
+LLM_MAX_TOKENS=512
+
+# --- Structured / episodic store ---
+DATABASE_URL=sqlite+pysqlite:///./context_bridge.db
+
+# --- Working memory ---
+# Provider: "memory" (in-process) or "redis".
+WORKING_PROVIDER=memory
+REDIS_URL=redis://localhost:6379/0
+WORKING_TTL_SECONDS=3600
+
+# --- Retrieval defaults ---
+DEFAULT_TOP_K=8
+DEFAULT_TOKEN_BUDGET=2048
+PREFETCH_LIMIT=50
+MMR_LAMBDA=0.6
+
+# --- Write policy ---
+DEDUP_THRESHOLD=0.95
+MIN_CONFIDENCE=0.0
+CHUNK_SIZE_TOKENS=256
+CHUNK_OVERLAP_TOKENS=32
+
+# --- Maintenance ---
+# Background TTL sweep interval in seconds (0 disables the periodic job).
+SWEEP_INTERVAL_SECONDS=0
+# Full housekeeping cycle interval in seconds (0 disables); runs per-namespace
+# upkeep (auto-resolve / consolidate / lesson distillation) plus a TTL sweep.
+MAINTENANCE_INTERVAL_SECONDS=0
+MAINTENANCE_AUTO_RESOLVE=true
+MAINTENANCE_CONSOLIDATE=false
+MAINTENANCE_DISTILL_LESSONS=false
+
+# --- Event webhooks ---
+# Comma-separated URLs notified (best-effort) of notable memory events.
+WEBHOOK_URLS=
+WEBHOOK_TIMEOUT_SECONDS=5.0
+
+# --- Cognitive layer ---
+# Mask secrets/PII before content enters the shared pool.
+REDACT_PII=false
+# How strongly outcome feedback re-ranks recall (0 disables).
+FEEDBACK_WEIGHT=0.15
+# Reflective consolidation: cluster size + similarity threshold.
+CONSOLIDATION_MIN_CLUSTER=3
+CONSOLIDATION_SIMILARITY=0.83
+# Flag contradictions between memories on write.
+DETECT_CONTRADICTIONS=false
+CONTRADICTION_SIMILARITY=0.80
+# Extract an entity/relation knowledge graph from writes.
+GRAPH_EXTRACTION=false
+# Failure memory: raise relevant lessons from past mistakes on recall.
+LESSONS_ENABLED=true
+LESSONS_TOP_K=3
+# Minimum trigger<->query similarity to surface a lesson.
+LESSONS_MIN_SCORE=0.20
+# Auto-distil lessons by clustering memories implicated in failures.
+LESSON_DISTILL_MIN_CLUSTER=2
+LESSON_DISTILL_SIMILARITY=0.83
+# Belief revision: demote memories that lose a contradiction.
+BELIEF_REVISION=true
+CONFLICT_LOSER_DECAY=0.5
+# How strongly recall demotes low-confidence memories (0 disables).
+CONFIDENCE_WEIGHT=0.5
+# Authority gap (trust + feedback) needed to auto-close a contradiction.
+AUTO_RESOLVE_MIN_GAP=0.3

context_bridge_memory-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,31 @@
+name: Bug report
+description: Report a problem with Context Bridge
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including what you expected.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps, code, or requests that trigger the issue.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version / commit
+    validations:
+      required: false
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, vector store / embedder configuration.
+    validations:
+      required: false

context_bridge_memory-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/sa-aris/context-bridge/security/advisories/new
+    about: Please report security issues privately, not as public issues.

context_bridge_memory-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature request
+description: Suggest an idea or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What problem would this solve? What's the use case?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How might it work? API sketch, configuration, behavior.
+    validations:
+      required: false
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

context_bridge_memory-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What does this change do and why? -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation / tooling
+
+## Checklist
+
+- [ ] `ruff check src tests` passes
+- [ ] `ruff format --check src tests` passes
+- [ ] `mypy src` passes
+- [ ] `pytest` passes
+- [ ] Added/updated tests for the change
+- [ ] Updated docs / CHANGELOG where relevant

context_bridge_memory-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install project
+        run: uv pip install --system -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check src tests
+
+      - name: Format check (ruff)
+        run: ruff format --check src tests
+
+      - name: Type check (mypy)
+        run: mypy src
+
+      - name: Test (pytest)
+        run: pytest --cov=context_bridge --cov-report=term-missing

context_bridge_memory-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Release
+
+on:
+  # Cut a release by bumping the version and touching `.release-trigger`.
+  push:
+    branches: ["main"]
+    paths: [".release-trigger"]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check artifacts
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    needs: build
+    # Only when triggered by a version tag; a manual run just builds & publishes.
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  pypi-publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Publishes via OIDC trusted publishing. Requires a PyPI trusted publisher
+    # for this repo and a GitHub environment named 'pypi'.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

context_bridge_memory-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Local state
+*.db
+*.sqlite3
+.env
+.fastembed_cache/
+qdrant_storage/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

context_bridge_memory-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files

context_bridge_memory-0.1.0/.release-trigger

@@ -0,0 +1 @@
+release: v0.1.0

context_bridge_memory-0.1.0/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-26
+
+### Added
+
+- Shared-memory core: governed write path (chunk → embed → dedup/confidence →
+  persist → log) and token-budgeted read path (hybrid search → rerank → MMR →
+  assemble).
+- Three memory tiers: working (in-process/Redis), semantic (Qdrant dense +
+  sparse), and episodic/provenance (SQLAlchemy + Alembic).
+- FastAPI service under a `/v1` API surface, plus sync and async SDK clients.
+- Hybrid retrieval with client-side Reciprocal Rank Fusion, cross-encoder
+  reranking (FastEmbed) and MMR diversification.
+- Small-to-big chunking with parent documents stored once in SQL.
+- TTL decay: query-time filtering plus a `/maintenance/sweep` endpoint and an
+  optional background sweeper.
+- Optional abstractive summarizer via any OpenAI-compatible endpoint, with an
+  extractive fallback.
+- Security: opt-in API-key auth (constant-time comparison), namespace-scoped
+  keys, and a pluggable rate limiter (in-memory or Redis).
+- Batch write and paginated listing endpoints.
+- Observability: Prometheus metrics at `/metrics`, request-ID propagation and a
+  structured global error handler.
+- Packaging: Apache-2.0 license, multi-stage Dockerfile, GitHub Actions CI, `py.typed`.
+- External providers: OpenAI / Cohere embedders and the Cohere reranker.
+- Streaming recall via Server-Sent Events (`/v1/memory/query/stream`).
+- RBAC: per-key namespace globs with read/write permissions (`API_KEY_POLICIES`).
+- Observability extras: Prometheus + Grafana stack, OpenTelemetry tracing.
+- Helm chart and a runnable token-savings benchmark.
+- Right-to-be-forgotten deletion by namespace/session, embedding-dimension
+  guard, bounded input sizes, and credential-safe CORS defaults.
+- Tag-driven release workflow (GitHub Release + PyPI trusted publishing).
+- Cognitive layer (opt-in, behind protocols): reflective consolidation,
+  contradiction detection & truth-maintenance, a knowledge-graph layer,
+  outcome-feedback re-ranking, and PII/secret redaction on write.
+- Collective learning: per-namespace agent reputation profiles, task-outcome
+  credit propagation, and procedural memory (playbooks with success tracking).
+- Salient distillation: score ephemeral conversational turns and promote only
+  the dwelled-upon ones into durable, cross-session memory
+  (`/v1/sessions/{id}/turns` + `/distill`).
+- Temporal recall: date-aware context (`include_dates`) and `since`/`until`
+  time-window filters on query.
+- Ontology alignment: merge surface variants of the same entity onto one
+  canonical name — automatically (`POST /v1/graph/align`) or by declaring an
+  alias (`POST /v1/graph/aliases`) — so agents converge on a shared vocabulary.
+- Collaboration-quality score: a single composite 0-100 metric per namespace
+  (recall hit-rate, feedback positivity, conflict health) at `GET /v1/quality`,
+  so a team can watch shared memory pay off over time.
+- Failure memory: capture a lesson from a mistake (`POST /v1/lessons`, or inline
+  with a failed `POST /v1/outcomes`) and have relevant lessons proactively raised
+  as guardrails on top of recall — so the team stops repeating the same errors.
+  Lessons rank by trigger similarity, severity and proven helpfulness, and can be
+  confirmed (`POST /v1/lessons/{id}/confirm`).
+- Preflight briefing (`POST /v1/preflight`): before starting a task, get the
+  lessons to avoid and the playbooks that worked, in one call.
+- Belief revision: resolving a contradiction now decays the *losing* memory's
+  confidence, and recall is confidence-weighted, so discredited memories sink and
+  repeated losses retire them — the pool changes its mind given better evidence.
+- Auto lesson distillation (`POST /v1/lessons/distill`): cluster memories
+  implicated in failures (net-negative feedback) into auto-drafted lessons, with
+  no human in the loop.
+- Recall explainability: every recalled chunk now carries per-signal scores
+  (match, feedback, confidence, age) and a short human-readable reason for *why*
+  it was retrieved.
+- Memory health panel (`GET /v1/namespaces/{ns}/health`): one pulse-check of a
+  namespace — volume, trust distribution (active/demoted/retired), average
+  confidence, open conflicts, lesson and agent counts, and quality score.
+- Auto conflict resolution (`POST /v1/conflicts/auto-resolve`): close
+  contradictions on their own when one memory's authority (trust + feedback)
+  decisively leads, leaving genuinely ambiguous cases for a human.
+- Belief timeline / memory diff (`GET /v1/namespaces/{ns}/beliefs?query=…`):
+  trace how belief about a topic evolved over time, showing which claim fell out
+  of favour and when.
+- Scheduled maintenance: a one-call housekeeping cycle (`POST /v1/maintenance/run`)
+  and an optional background loop (`MAINTENANCE_INTERVAL_SECONDS`) that sweeps TTL
+  and runs per-namespace auto-resolve / consolidation / lesson distillation.
+- Event webhooks: best-effort notifications (`WEBHOOK_URLS`) for notable events —
+  `conflict.opened`, `conflict.resolved`, `lesson.created` — that never block or
+  fail a memory operation.
+- Namespace portability: export a namespace's memories, lessons and procedures to
+  a portable, vector-free document (`GET /v1/namespaces/{ns}/export`) and restore
+  it — re-embedding on the way in — into any namespace (`POST …/import`).
+- Cognitive-layer observability: `cb_events_total{type}`, `cb_maintenance_runs_total`
+  metrics and Grafana panels for conflicts, lessons and maintenance.
+- Extended SDK: synchronous and async clients now cover the learning loop, failure
+  memory, preflight, truth-maintenance, graph, quality, health, belief timeline
+  and namespace import/export.
+- Runnable offline demo (`examples/quickstart.py`) and an embedded terminal
+  render of its output in the README.

context_bridge_memory-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and unwelcome sexual attention
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers. All complaints will be reviewed and
+investigated promptly and fairly.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1.
+
+[homepage]: https://www.contributor-covenant.org

context_bridge_memory-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to Context Bridge
+
+Thanks for your interest in improving Context Bridge! This guide covers the
+basics for getting set up and submitting changes.
+
+## Development setup
+
+```bash
+# Create an environment and install with dev extras
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Optional: spin up Qdrant + Postgres + Redis locally
+docker compose up -d
+```
+
+## Before you open a pull request
+
+Run the full local gate — CI runs the same checks:
+
+```bash
+ruff check src tests        # lint
+ruff format --check src tests
+mypy src                    # type-check
+pytest                      # tests (hermetic; no network needed)
+```
+
+The default test suite is fully offline: it uses an in-process Qdrant
+(`:memory:`), SQLite, and a deterministic hashing embedder. Tests that need a
+downloaded model (e.g. the FastEmbed reranker smoke test) skip automatically
+when the model is unavailable.
+
+## Guidelines
+
+- **Keep providers behind their protocols.** New vector stores, embedders,
+  rerankers, working-memory or summarizer backends should implement the
+  existing `Protocol` in the relevant `core/*` package — don't couple callers
+  to a concrete backend.
+- **Add tests** for new behavior. Prefer hermetic tests; gate anything needing
+  network/models behind `pytest.importorskip` / `pytest.skip`.
+- **Conventional commits.** Use prefixes like `feat:`, `fix:`, `docs:`,
+  `test:`, `chore:`, `refactor:`.
+- **Type everything.** `mypy src` must pass.
+
+## Cutting a release
+
+Releases are tag-driven. Bump `version` in `pyproject.toml`, update
+`CHANGELOG.md`, then:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The `Release` workflow builds the sdist/wheel and creates a GitHub Release with
+generated notes, then publishes to PyPI via OIDC **trusted publishing**. One-time
+setup:
+
+1. On PyPI, add a **trusted publisher** for this repo (workflow `release.yml`,
+   environment `pypi`) — no token needed.
+2. On GitHub, create an **environment** named `pypi` (Settings → Environments).
+
+Then tagging a version cuts the release and publishes automatically.
+
+## Reporting bugs / requesting features
+
+Open an issue using the provided templates. For security issues, please follow
+[SECURITY.md](SECURITY.md) instead of filing a public issue.

context_bridge_memory-0.1.0/Dockerfile

@@ -0,0 +1,43 @@
+# syntax=docker/dockerfile:1
+
+# --- builder: install dependencies into a venv ---
+FROM python:3.11-slim AS builder
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR /app
+
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Install dependencies first for better layer caching.
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install ".[fastembed,redis,postgres]"
+
+# --- runtime: minimal image ---
+FROM python:3.11-slim AS runtime
+
+ENV PATH="/opt/venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    API_HOST=0.0.0.0 \
+    API_PORT=8000
+
+# Run as a non-root user.
+RUN useradd --create-home --uid 10001 appuser
+WORKDIR /app
+
+COPY --from=builder /opt/venv /opt/venv
+COPY --from=builder /app/src /app/src
+COPY pyproject.toml README.md ./
+
+USER appuser
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+    CMD python -c "import urllib.request,os;urllib.request.urlopen(f'http://127.0.0.1:{os.environ.get(\"API_PORT\",\"8000\")}/health').read()" || exit 1
+
+CMD ["python", "-m", "context_bridge"]