prodedify-memory 0.0.0__tar.gz → 0.2.1__tar.gz

prodedify_memory-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+# Engine CI (prodedify/memory).
+#
+# The engine's migration history is its most fragile shared surface — parallel
+# worktrees that branch off the same commit can each pick the same revision number
+# and fork the history into two heads, which silently breaks `alembic upgrade head`
+# and the standalone-independence bootstrap. Nothing ran at engine-PR time to catch
+# it (the SAP-IND-1 / PRD-11b two-`0006`-heads fork slipped through to rehearsal),
+# so this is the engine's first CI: a BLOCKING migration-graph guard + ruff + the
+# test suite. It mirrors the Supabase duplicate-timestamp guard (mono #129), one
+# layer up — colliding timestamps there, a forked history here.
+name: engine-ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    runs-on: [self-hosted, linux, x64]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install engine (migrations + mcp + dev)
+        run: pip install -e '.[migrations,mcp,dev]'
+
+      # The headline gate: fail the build on a forked history (>1 head) or an
+      # unresolvable revision graph (orphan down_revision / cycle).
+      - name: Migration-graph guard — single head + integrity (BLOCKING)
+        run: python scripts/check_migration_graph.py
+
+      - name: ruff
+        run: ruff check .
+
+      # DB-backed suites skip without SAPERE_TEST_* env; the migration-graph test
+      # and the pure-Python suites run. `-m pytest` puts the repo root on sys.path
+      # so the guard's `scripts` package imports.
+      - name: pytest
+        run: python -m pytest -q

prodedify_memory-0.2.1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+.env
+# raw public-benchmark dataset cache (spec §2.3) — never committed
+prodedify_memory/benchmark/.cache/

prodedify_memory-0.2.1/CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md — prodedify_memory (Engine Repo)
+
+This file governs work **inside the engine repo** (`prodedify_memory`, vendored at `backend/vendor/memory/`). It is its own repository with its own authority — the monorepo CLAUDE.md does not cover the engine-specific rules below. When working here, these rules take precedence for engine concerns.
+
+## What this repo is
+
+`prodedify_memory` is the **Sapere memory engine** — the bitemporal, governed, replayable decision/fact/grounding substrate. It is consumed by the monorepo backend as a vendored submodule and is pinned by SHA. Two properties define everything below:
+
+1. **It is the Alembic migration authority.** The engine's `alembic/` migrations are the canonical, standalone schema definition. The monorepo's Supabase migrations are dual-authored *mirrors* — but the Alembic authority is what must stand the schema up alone.
+2. **It must be standalone-installable.** Sapere ships independently (door-3/self-hosted/BYOC). The engine must stand up with **zero Plinth tables**, no imports from the monorepo backend, no foreign keys into any sibling-product schema, and `workspace_id` as an **opaque tenant key** (not an FK). This is the independence guarantee — it is load-bearing, not aspirational.
+
+## Migration discipline (the most dangerous surface — read first)
+
+The engine's migration history is the single most fragile shared surface in the whole system, because its failures reach **deploy-time and fresh-bootstrap, never CI**. Three near-misses have already occurred (duplicate Supabase timestamp, submodule-pointer regression, two-heads fork). Therefore:
+
+- **Single head, always.** Before opening any PR that adds a migration, run `alembic heads` and confirm it returns **exactly one**. Parallel worktrees branching off the same engine commit *will* pick colliding revision numbers — if you find two heads, STOP and surface it (the fix is an `alembic merge` revision; do not paper over it).
+- **Every `down_revision` must resolve.** No orphan revisions. The history graph must be a single connected lineage.
+- **Fresh-DB verification is mandatory for any migration.** Verify `alembic upgrade head` runs clean and deterministically on a **fresh ephemeral DB with zero Plinth tables** — not just against an already-migrated DB (which hides forks and ordering bugs). This is the standalone-independence test; it is the real proof, not a formality.
+- **Dual-authoring contract:** schema changes are authored in BOTH this repo (Alembic) AND the monorepo (Supabase). The engine Alembic migration is **FK-free** (the independence gate); the Supabase mirror may carry FKs to monorepo tables. The `prodedify/memory` PR **merges before** the monorepo bumps the submodule pointer — never pin the monorepo to an unmerged engine commit.
+- **Merge revisions are history-only.** An `alembic merge` revision has no DDL and no Supabase counterpart (prod already has the merged migrations applied). Don't author a phantom Supabase mirror for a merge.
+- **`pgvector`/extensions:** vector ops use bare `vector`/`vector_cosine_ops`/`<=>` (extension lives in `public`, on the migration role's search_path). Anything in the `extensions` schema (e.g. pgcrypto) must be schema-qualified — local search_path includes `extensions`, prod's does not (this caused a prod migration failure). Confirm the extension's schema before using it unqualified.
+
+## Self-verification (no false greens)
+
+- **Verify under `app_rw` ONLY** on ephemeral databases — never owner, superuser, or `service_role`. A migration or RLS test that passes under a privileged role is a **false green**: privileged roles bypass RLS, so isolation/policy tests must run as the least-privileged runtime role to mean anything.
+- Spin up an ephemeral DB, apply the full chain, run the suite, tear it down. Do not verify against a shared/persistent DB.
+- The existing engine test suite must stay green; `ruff` clean. New schema → its RLS/isolation must be covered (registered in the policy-source/invariant mechanism, even when the table has no ORM model — model-less tables still need isolation coverage).
+
+## Tenancy & RLS (engine-side)
+
+- Every tenant-scoped table carries `workspace_id` and is protected by **FORCE ROW LEVEL SECURITY** with the GUC-based fail-closed policy template: `workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid`. The empty-string→NULL coercion is what makes it fail closed (an unset GUC matches nothing, never everything).
+- The engine self-scopes: it sets `app.workspace_id` from the `workspace_id` argument passed in (it does not depend on the monorepo's request middleware). Engine ops are RLS-scoped **by argument**, independent of any request context.
+- Derived caches (e.g. embeddings) may be mutable (`app_rw` gets full CRUD) — that is NOT a governed-record deletion. The no-hard-delete rule binds **governed records** (decisions, facts, grounding, authority/audit rows), not their derived caches.
+
+## Vendor-neutrality / independence (Sapere ships alone)
+
+- **No sibling-product names in the engine schema or code.** The graph-edge-creator triad is `system / agent / user` — `kilnai` was removed (SAP-IND-1) and must never reappear. Any AI/agent author is `agent`; never a product name.
+- **Truthful provenance:** agent-authored writes record `created_by_ai = True` (→ `agent`), never defaulted to `user`. The engine is a system-of-record; the provenance it stores must be true.
+- **No imports from the monorepo backend, no FK into Plinth or any sibling schema.** If a change seems to need either, STOP — it breaks the standalone guarantee.
+- The package namespace `prodedify_*` is fine (company namespace, not a sibling product). The line is **sibling-product coupling**, not company branding.
+
+## Authority & governed writes
+
+- The substrate is bitemporal: `recorded_at`/`invalidated_recorded_at` (transaction-time, system-owned, never caller-set) and `valid_from`/`valid_until` (valid-time, caller-assertable). Transaction-time is the basis of tamper-evidence — nothing but the record/supersede path writes `recorded_at`.
+- Authority states: `ASSERTED` / `PROPOSED` / `QUARANTINED`. Writes resolve through the policy engine (`resolve_write_authority`); unknown sources fail closed to `PROPOSED`. Promotion is attributed, append-only, never a silent flip.
+- Audit (grounding/authority events) is append-only and hash-chained — no UPDATE/DELETE under FORCE RLS. "Forget" is governed demotion, never a hard delete.
+
+## Human levers (never performed by an agent session)
+
+- Bumping the monorepo's submodule pointer to an engine commit (done in the monorepo, after the engine PR merges — and the pointer diff is eyeballed before push).
+- Rotating signing keys / changing the JWT alg (would invalidate live tokens).
+- Issuing real credentials, registering real providers.
+
+End engine work at **"rehearsed green (fresh ephemeral DB, app_rw) + PR open."** Do not apply, deploy, or move pointers.
+
+## The loop
+
+branch off the engine repo's `main` → Step 0 (inspect/decide, STOP for confirm on anything touching the migration graph or a shared decision) → build → fresh-ephemeral-`app_rw` rehearsal incl. `alembic heads == 1` and zero-Plinth-tables bootstrap → open PR → stop.

prodedify_memory-0.2.1/LICENSE

@@ -0,0 +1,89 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Prodedify
+Licensed Work:        prodedify-memory
+                      The Licensed Work is (c) 2026 Prodedify.
+Additional Use Grant: You may use the Licensed Work for non-production
+                      purposes only: development, testing, and evaluation.
+                      Any production use, and any use of the Licensed Work
+                      to provide a product or service to third parties,
+                      requires a separate commercial license from the
+                      Licensor (hello@prodedify.com).
+Change Date:          2030-07-06
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact hello@prodedify.com.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or any later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses
+   without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

prodedify_memory-0.2.1/Makefile

@@ -0,0 +1,37 @@
+# Sapere standalone dev data-plane (ADR-008). See docker-compose.dev.yml.
+COMPOSE := docker compose -f docker-compose.dev.yml
+SAPERE_DATABASE_URL ?= postgresql://postgres:postgres@127.0.0.1:5434/sapere
+
+.PHONY: dev-up dev-studio dev-bootstrap dev-down dev-reset eval eval-full
+
+# G5 retrieval-eval harness. `eval` is the reproducible one-command deliverable:
+# stands up the standalone PG + schema, then runs the fixture through every arm,
+# prints the quality + latency tables, and gates against the committed baseline.
+BENCH_OWNER ?= postgresql://postgres:postgres@127.0.0.1:5434/sapere
+BENCH_APP_RW ?= postgresql://app_rw:app_rw@127.0.0.1:5434/sapere
+
+eval: dev-up dev-bootstrap ## run the fixture benchmark + gate (prints both tables)
+	SAPERE_TEST_OWNER_URL=$(BENCH_OWNER) SAPERE_TEST_APP_RW_URL=$(BENCH_APP_RW) \
+	  python -m prodedify_memory.benchmark.cli --corpus fixture --embedder fake --judge scripted --gate
+
+eval-full: ## full-scale run — CORPUS= ADAPTER= LIMIT= INFLATE= JUDGE= REPEATS= pass-through, no gate
+	SAPERE_TEST_OWNER_URL=$(BENCH_OWNER) SAPERE_TEST_APP_RW_URL=$(BENCH_APP_RW) \
+	  python -m prodedify_memory.benchmark.cli --corpus $(or $(CORPUS),fixture) \
+	  --adapter $(or $(ADAPTER),none) --inflate $(or $(INFLATE),0) \
+	  --repeats $(or $(REPEATS),20) --judge $(or $(JUDGE),none) --embedder $(or $(EMBEDDER),fake)
+
+dev-up: ## standalone Postgres + pgweb viewer (http://localhost:8081)
+	$(COMPOSE) up -d sapere-db pgweb
+
+dev-studio: ## also bring up Supabase Studio (http://localhost:54330)
+	$(COMPOSE) --profile studio up -d
+
+dev-bootstrap: ## apply the engine schema (incl. 0007 app_rw grants; needs an installed '.[migrations]' env)
+	SAPERE_DATABASE_URL=$(SAPERE_DATABASE_URL) alembic upgrade head
+	@echo "bootstrapped head: $$($(COMPOSE) exec -T sapere-db psql -U postgres -d sapere -tAc 'select version_num from alembic_version')"
+
+dev-down: ## stop the stack (keeps data)
+	$(COMPOSE) --profile studio down
+
+dev-reset: ## stop + delete the volume (fresh DB on next up)
+	$(COMPOSE) --profile studio down -v

prodedify_memory-0.2.1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: prodedify-memory
+Version: 0.2.1
+Summary: Organization memory engine: a compounding knowledge graph of decisions, entities, and their relationships — queryable by humans and agents (MCP).
+License: Business Source License 1.1
+        
+        Parameters
+        
+        Licensor:             Prodedify
+        Licensed Work:        prodedify-memory
+                              The Licensed Work is (c) 2026 Prodedify.
+        Additional Use Grant: You may use the Licensed Work for non-production
+                              purposes only: development, testing, and evaluation.
+                              Any production use, and any use of the Licensed Work
+                              to provide a product or service to third parties,
+                              requires a separate commercial license from the
+                              Licensor (hello@prodedify.com).
+        Change Date:          2030-07-06
+        Change License:       Apache License, Version 2.0
+        
+        For information about alternative licensing arrangements for the Licensed
+        Work, please contact hello@prodedify.com.
+        
+        Notice
+        
+        Business Source License 1.1
+        
+        Terms
+        
+        The Licensor hereby grants you the right to copy, modify, create derivative
+        works, redistribute, and make non-production use of the Licensed Work. The
+        Licensor may make an Additional Use Grant, above, permitting limited
+        production use.
+        
+        Effective on the Change Date, or the fourth anniversary of the first publicly
+        available distribution of a specific version of the Licensed Work under this
+        License, whichever comes first, the Licensor hereby grants you rights under
+        the terms of the Change License, and the rights granted in the paragraph
+        above terminate.
+        
+        If your use of the Licensed Work does not comply with the requirements
+        currently in effect as described in this License, you must purchase a
+        commercial license from the Licensor, its affiliated entities, or authorized
+        resellers, or you must refrain from using the Licensed Work.
+        
+        All copies of the original and modified Licensed Work, and derivative works
+        of the Licensed Work, are subject to this License. This License applies
+        separately for each version of the Licensed Work and the Change Date may vary
+        for each version of the Licensed Work released by Licensor.
+        
+        You must conspicuously display this License on each original or modified copy
+        of the Licensed Work. If you receive the Licensed Work in original or
+        modified form from a third party, the terms and conditions set forth in this
+        License apply to your use of that work.
+        
+        Any use of the Licensed Work in violation of this License will automatically
+        terminate your rights under this License for the current and all other
+        versions of the Licensed Work.
+        
+        This License does not grant you any right in any trademark or logo of
+        Licensor or its affiliates (provided that you may use a trademark or logo of
+        Licensor as expressly required by this License).
+        
+        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+        AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+        EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+        TITLE.
+        
+        MariaDB hereby grants you permission to use this License's text to license
+        your works, and to refer to it using the trademark "Business Source License",
+        as long as you comply with the Covenants of Licensor below.
+        
+        Covenants of Licensor
+        
+        In consideration of the right to use this License's text and the "Business
+        Source License" name and trademark, Licensor covenants to MariaDB, and to all
+        other recipients of the licensed work to be provided by Licensor:
+        
+        1. To specify as the Change License the GPL Version 2.0 or any later version,
+           or a license that is compatible with GPL Version 2.0 or any later version,
+           where "compatible" means that software provided under the Change License
+           can be included in a program with software provided under GPL Version 2.0
+           or a later version. Licensor may specify additional Change Licenses
+           without limitation.
+        
+        2. To either: (a) specify an additional grant of rights to use that does not
+           impose any additional restriction on the right granted in this License, as
+           the Additional Use Grant; or (b) insert the text "None".
+        
+        3. To specify a Change Date.
+        
+        4. Not to modify this License in any other way.
+License-File: LICENSE
+Classifier: License :: Other/Proprietary License
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: networkx>=3.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: migrations
+Requires-Dist: alembic>=1.13; extra == 'migrations'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'migrations'

prodedify_memory-0.2.1/README.md

@@ -0,0 +1,77 @@
+# prodedify-memory
+
+**The organization memory engine.** A compounding knowledge graph of
+decisions, entities, and relationships — industry-agnostic via an
+injectable `EntityRegistry`, queryable by humans and agents over MCP.
+
+Extracted from the Prodedify platform (KG_EXTRACTION_SPEC, 2026-06-11);
+the Prodedify monorepo is the first consumer. **Private — proprietary.**
+
+## Standalone install (owns its schema, not a database)
+
+The engine owns its schema but takes an **injected** Postgres connection — no
+bundled database. The schema is self-contained (no foreign keys to host tables;
+`workspace_id` is a plain tenant partition key), so it bootstraps on an empty
+Postgres:
+
+```bash
+pip install -e '.[migrations]'
+
+# Fresh standalone database:
+export SAPERE_DATABASE_URL=postgresql://user:pass@host:5432/sapere
+alembic upgrade head        # creates the engine's tables + enums + indexes
+
+# Existing install whose tables already exist (e.g. a hosted Supabase created
+# by the monorepo migrations) — adopt, don't recreate:
+alembic stamp head
+```
+
+The same engine embeds in Plinth (inject the shared platform Postgres) or runs
+standalone (inject a dedicated one). Migrations run on a sync driver; the app
+connects however it likes (asyncpg).
+
+## What's here (KG-0)
+
+| Module | Purpose |
+|---|---|
+| `registry` | `EntityRegistry` — the deployment's vocabulary (entity/relationship types, decision categories). `PRODEDIFY_REGISTRY` mirrors production. |
+| `store` | `MemoryStore` — read-only, **workspace-bound** query layer (search, decisions, conflicts, timeline, neighbors, shortest path, communities). |
+| `provenance` | `EXTRACTED / INFERRED / AMBIGUOUS` trust labels + default classifier. |
+| `mcp` | The memory as an MCP server (stdio + Streamable HTTP). |
+| `benchmark` | Memory-ROI metric: graph-grounded context vs raw corpus tokens. |
+
+KG-1 moves the write/intelligence core (graph service, clustering,
+temporal analysis) here from the monorepo. See the spec for phases.
+
+## Quickstart (against a Prodedify-schema database)
+
+```bash
+pip install -e '.[mcp,dev]'
+
+python -m prodedify_memory.mcp.server \
+  --database-url postgresql+asyncpg://user:pass@host:5432/db \
+  --workspace-id <workspace-uuid>
+```
+
+Register with Claude Code:
+
+```bash
+claude mcp add prodedify-memory -- python -m prodedify_memory.mcp.server \
+  --database-url $MEMORY_DATABASE_URL --workspace-id $WORKSPACE_ID
+```
+
+Tools exposed: `memory_stats`, `query_memory`, `get_decisions`,
+`get_conflicts`, `get_timeline`, `get_neighbors`, `shortest_path`,
+`get_communities`.
+
+## Security
+
+One server = one workspace (tenant isolation is structural). Read-only.
+Parameterized SQL only. HTTP transport refuses non-loopback binds without
+an API key. See SECURITY.md.
+
+## Tests
+
+```bash
+pytest -q
+```

prodedify_memory-0.2.1/SECURITY.md

@@ -0,0 +1,38 @@
+# Security model
+
+## Tenant isolation is structural
+
+A `MemoryStore` (and therefore an MCP server instance) is bound to exactly
+one `workspace_id` at construction. There is no tool parameter, header, or
+query that can address another tenant's data — cross-tenant access is not
+an authorization failure mode, it is unrepresentable.
+
+## Read-only by default; one opt-in write
+
+The default tool surface never mutates the graph. The single write tool
+(`record_decision`) exists only when the operator starts the server with
+`--allow-writes` AND `--default-project-id`; it records operator-stated
+decisions with `provenance=EXTRACTED`, remains workspace-bound, validates
+category against the registry, and sanitizes all text. All other writes
+(extraction, conflict scanning) remain with the consuming application.
+
+## Input handling
+
+- All SQL is parameterized (SQLAlchemy Core `text()` with bound params).
+- Free-text queries are control-character-stripped and capped at 500
+  chars before use.
+- Limits are clamped server-side (max 50 rows; path depth max 5).
+- Entity/relationship types are validated against the deployment's
+  EntityRegistry before touching the graph.
+
+## Transports
+
+- stdio (default): inherits the parent process's security context.
+- Streamable HTTP: binds loopback by default; refuses to bind a
+  non-loopback host unless an API key is configured. Always run behind
+  TLS termination in shared environments.
+
+## Data classification
+
+Graph contents are customer organizational memory — treat every value as
+confidential. Logs must never include row contents (IDs and counts only).

prodedify_memory-0.2.1/alembic/env.py

@@ -0,0 +1,62 @@
+"""Alembic environment for the standalone memory engine.
+
+Schema comes from the engine's own models (`prodedify_memory.models.Base`); the
+database connection is injected via SAPERE_DATABASE_URL or DATABASE_URL. No
+bundled database — the engine owns its schema, the host owns the server.
+"""
+
+from __future__ import annotations
+
+import os
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from prodedify_memory.models import Base
+
+config = context.config
+
+target_metadata = Base.metadata
+
+
+def _db_url() -> str:
+    url = os.environ.get("SAPERE_DATABASE_URL") or os.environ.get("DATABASE_URL")
+    if not url:
+        raise RuntimeError(
+            "Set SAPERE_DATABASE_URL (or DATABASE_URL) to the target Postgres."
+        )
+    # Migrations run on a sync driver regardless of how the app connects.
+    return (
+        url.replace("postgresql+asyncpg://", "postgresql+psycopg://")
+        .replace("postgres://", "postgresql+psycopg://")
+        .replace("postgresql://", "postgresql+psycopg://")
+    )
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=_db_url(),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    section = config.get_section(config.config_ini_section) or {}
+    section["sqlalchemy.url"] = _db_url()
+    connectable = engine_from_config(
+        section, prefix="sqlalchemy.", poolclass=pool.NullPool
+    )
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

prodedify_memory-0.2.1/alembic/script.py.mako

@@ -0,0 +1,23 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

prodedify_memory-0.2.1/alembic/versions/0001_baseline.py

@@ -0,0 +1,86 @@
+"""baseline — the memory engine's self-contained graph schema
+
+Creates the engine's own tables from its models (knowledge_graph_edges,
+product_decisions, knowledge_graph_cluster_runs, knowledge_graph_communities,
+knowledge_graph_temporal_snapshots), including bi-temporal validity columns.
+The schema has no foreign keys to any host tables — workspace_id is a plain
+partition key — so a standalone Sapere bootstraps against an empty Postgres.
+
+Existing installs whose tables already exist (e.g. the hosted Supabase, created
+by the monorepo migrations) should `alembic stamp head` instead of upgrading.
+
+Revision ID: 0001_baseline
+Revises:
+Create Date: 2026-06-13
+"""
+
+from alembic import op
+
+from prodedify_memory.models import Base
+
+revision = "0001_baseline"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+
+    # 1. The two fixed-vocabulary enums that survived KG-2 (the ontology enums
+    #    are varchar now). create_type=False on the models means create_all
+    #    won't make these — so we make them first.
+    op.execute(
+        "DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname="
+        "'graph_edge_creator') THEN CREATE TYPE graph_edge_creator AS ENUM "
+        "('system','kilnai','user'); END IF; END $$;"
+    )
+    op.execute(
+        "DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname="
+        "'decision_status') THEN CREATE TYPE decision_status AS ENUM "
+        "('active','superseded','reversed','under_review'); END IF; END $$;"
+    )
+
+    # 2. Tables from the engine's own models (single source of truth, includes
+    #    valid_from/valid_until).
+    Base.metadata.create_all(bind, checkfirst=True)
+
+    # 3. Correctness + hot-path indexes the bare models don't declare.
+    op.execute(
+        "CREATE UNIQUE INDEX IF NOT EXISTS idx_kge_unique_edge "
+        "ON knowledge_graph_edges "
+        "(source_type, source_id, target_type, target_id, relationship_type) "
+        "WHERE deleted_at IS NULL"
+    )
+    op.execute(
+        "CREATE UNIQUE INDEX IF NOT EXISTS idx_kgc_unique "
+        "ON knowledge_graph_communities "
+        "(entity_type, entity_id, project_id, cluster_run_id)"
+    )
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS idx_pd_live ON product_decisions "
+        "(workspace_id, valid_from) "
+        "WHERE valid_until IS NULL AND status = 'active' AND deleted_at IS NULL"
+    )
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS idx_kge_source "
+        "ON knowledge_graph_edges (source_type, source_id) "
+        "WHERE deleted_at IS NULL"
+    )
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS idx_kge_target "
+        "ON knowledge_graph_edges (target_type, target_id) "
+        "WHERE deleted_at IS NULL"
+    )
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS idx_pd_project_active "
+        "ON product_decisions (project_id) "
+        "WHERE status = 'active' AND deleted_at IS NULL"
+    )
+
+
+def downgrade() -> None:
+    bind = op.get_bind()
+    Base.metadata.drop_all(bind, checkfirst=True)
+    op.execute("DROP TYPE IF EXISTS decision_status")
+    op.execute("DROP TYPE IF EXISTS graph_edge_creator")