Theme

Vendor decoupling — remove consumer-specific assumptions from the product surface.

Changed

• guard_no_test_project(): the production floor is no longer hardcoded. It now reads the
  GUC pgmnemo.test_project_floor (default 0 = floor check disabled). Consumers opt in via
  SET pgmnemo.test_project_floor = <N>; — the product no longer imposes a project-id numbering scheme.
• Documentation now cites the product's own spec (RFC-001) instead of an internal design-record id.

Notes

• No data-model or recall change; remember_fact/event/relation behaviour is unchanged.
• Upgrade: ALTER EXTENSION pgmnemo UPDATE TO '0.12.1';. Deployments relying on the old hard
  floor of 100 should add SET pgmnemo.test_project_floor = 100; (e.g. in their test harness).

Theme

Typed Write API — remember_fact / remember_event / remember_relation.
Adds three structured write functions to the extension. Existing recall API unchanged.

Positioning note (2026-06-24): Typed structured writes are industry parity — Mem0,
Zep/Graphiti, and Letta all expose entity/relation write primitives. This release
brings pgmnemo to write-side parity. Differentiation remains the single-plan SQL
architecture (write + supersession + recall in one Postgres plan, zero external
round-trips). No recall-quality improvement is claimed for this release.

Added

• pgmnemo.remember_fact(role, entity_key, property, value, confidence, has_contact_pii, embedding, source_type, project_id, commit_sha, artifact_hash)
  Writes a named property fact about an entity. Returns (id BIGINT, final_state TEXT).
  PII-aware state routing built in (ADR-61 D4): email/phone/address/telegram/full_name
  on person:* keys → candidate regardless of source; system non-PII → validated;
  auto_captured → candidate; agent_authored conf ≥ 0.8 non-PII → validated.
  Bitemporal supersession: different value → closes prior row, inserts new version_n+1.
  Merge: same value → updates confidence = GREATEST(existing, new), re-classifies state.
  Synthesizes artifact_hash = 'fact-<entity_key>:<property>' when caller omits it.
  Identity key: (lower(entity_key/property), project_id) with SELECT FOR UPDATE.

• pgmnemo.remember_event(role, entity_key, label, body, occurred_at, confidence, embedding, source_type, project_id, commit_sha, artifact_hash)
  Appends an immutable event record (content_type = 'event'). Returns BIGINT id.

• pgmnemo.remember_relation(role, from_key, to_key, relation_type, confidence, embedding, source_type, project_id, commit_sha, artifact_hash)
  Writes a directed typed relation (content_type = 'relation'). Idempotent on triple.
  Opportunistically links entity hubs via add_edge() when hub rows exist.
  Returns BIGINT id.

• pgmnemo.canonical_slug(type TEXT, label TEXT) → TEXT
  Normalises arbitrary text to ^(person|org|project|product|location|concept):[a-z0-9_]+$
  max 72 chars. IMMUTABLE PARALLEL SAFE.

• pgmnemo._has_contact_pii(property TEXT) → BOOLEAN
  Returns TRUE for {email, phone, address, telegram, full_name}. IMMUTABLE.

• pgmnemo.guard_no_test_project(project_id INT, allowed_db TEXT DEFAULT NULL)
  Safety guard for test harnesses. Raises when project_id ≤ 100.

• ix_entity_canonical_name_prj unique index on agent_lesson(lower(metadata->>'canonical_name'), project_id) for entity hub dedup.

• pg_regress tests: typed_recall_fast (0.12.0 upgrade path) and test_remember_fact (20 tests covering ADDENDUM-2 R1–R7).

• Spec: spec/v3/memory-era/RFC-001-ADDENDUM-2-write-api-learnings.md (7 correctness requirements) and RFC-001-ADDENDUM-typed-recall-coverage.md.

Migration from ingest_entity

Callers of ingest_entity can switch to remember_fact with the same
entity_key + project_id. Existing rows (version_n = 0 sentinel) are absorbed
on the first remember_fact write: prior row is closed, new row gets version_n = 1.
No schema migration required. To opt existing rows into content_type filtering,
run the bulk-update in spec/v3/memory-era/RFC-001-ADDENDUM-typed-recall-coverage.md.

Promote bulk-helper (for candidate PII rows)

To promote PII candidate rows after human review:

UPDATE pgmnemo.agent_lesson
SET state = 'validated', verified_at = NOW()
WHERE project_id = $1
  AND state = 'candidate'
  AND content_type = 'fact'
  AND <your_review_condition>;

No breaking changes

All existing function signatures unchanged. recall_fast, recall_lessons,
recall_hybrid, ingest, and add_edge are unmodified. New remember_* rows
are indistinguishable from ingest() rows to the recall stack.

Theme

Typed recall on the hot path — p_content_types mirrored to recall_fast() and
recall_lessons(). v0.11.0 added typed recall (p_content_types) to recall_hybrid()
only; Agency consumers and MCP pgmnemo.recall call recall_fast(), making the
0.11.0 filter unreachable without going through hybrid. This patch completes typed recall
by mirroring the identical parameter to the two hot-path functions.

Backward-compatible patch: all existing callers unchanged (new param defaults to NULL).

Added

• p_content_types TEXT[] DEFAULT NULL on recall_fast() (6th parameter, was 5).
  When non-NULL, adds WHERE content_type = ANY(p_content_types) pushdown before
  HNSW ranking. Uses ix_pgmnemo_content_type_active index (added in v0.11.0).
  NULL or omitted → all content types (backward compat). '{}' → zero rows.

• p_content_types TEXT[] DEFAULT NULL on recall_lessons() (8th parameter, was 7).
  On the hybrid path (when query_text present): forwarded to recall_hybrid() as its
  10th argument. On the vector-only path: applied as WHERE content_type = ANY(...).
  Same semantics as recall_fast() and recall_hybrid() — NULL → unchanged, '{}' → 0.

• Migration delta: pgmnemo--0.11.0--0.11.1.sql — DROPs old 5-param recall_fast
  and 7-param recall_lessons, CREATEs 6-param and 8-param overloads respectively.

• Flat install: pgmnemo--0.11.1.sql — fresh install via
  CREATE EXTENSION pgmnemo VERSION '0.11.1'.

• pg_regress test: typed_recall_fast — T1–T10 covering signature checks for both
  functions, NULL backward compat, single-type filter, empty-array guard, multi-type
  filter, recall_lessons vector-only path, and backward-compat identity check.

Migration notes

ALTER EXTENSION pgmnemo UPDATE TO '0.11.1' from 0.11.0 applies
pgmnemo--0.11.0--0.11.1.sql. DROPs the old recall_fast(5) and
recall_lessons(7) overloads; CREATEs 6-param and 8-param versions with
p_content_types DEFAULT NULL. All existing call sites with ≤5 (recall_fast) or ≤7
(recall_lessons) positional args continue to work unchanged.

No schema column changes. No data migration required.

Theme

Typed Memory — P0.2: optional p_content_types filter on recall_hybrid().
Adds per-call typed recall filtering to recall_hybrid() via a new 10th parameter
p_content_types TEXT[] DEFAULT NULL. Backwards-compatible minor release: existing
9-parameter callers are unaffected (NULL → all content types, same behaviour as before).

Competitive note (2026-06-23): Typed/categorised memory retrieval is not an
unclaimed lane — Zep and Memento already ship typed retrieval. This release brings
pgmnemo to feature parity on typed filtering; differentiation remains the
single-plan SQL architecture and provenance gating.

Added

• p_content_types TEXT[] DEFAULT NULL on recall_hybrid() (10th parameter).
  When non-NULL, restricts recall to lessons whose content_type column matches any
  of the supplied values (e.g. ARRAY['procedure','fact']). An empty array '{}'
  returns zero rows (explicit exclusion, not silent all-types fallback). NULL or
  omitted behaves identically to the pre-v0.11.0 9-parameter API. Uses the
  ix_pgmnemo_content_type_active partial index added in this migration for
  efficient pushdown. (ADR-61 §3 D3)

• content_type partial index (ix_pgmnemo_content_type_active) on
  agent_lesson (content_type) WHERE is_active AND t_valid_to = 'infinity'.

• Migration deltas: pgmnemo--0.10.0--0.11.0.sql and
  pgmnemo--0.10.1--0.11.0.sql (both upgrade paths supported).

• pg_regress test: typed_recall — T1–T8 covering signature check, backward
  compat, NULL explicit, single-type filter, empty-array guard, multi-type filter,
  bit-identical NULL vs old API, and index-pushdown subset check.

Migration notes

ALTER EXTENSION pgmnemo UPDATE TO '0.11.0' from 0.10.0 or 0.10.1 applies the
corresponding delta. The migration adds the content_type partial index
(ix_pgmnemo_content_type_active) and replaces recall_hybrid() with a 10-parameter
overload. No schema column changes; no data migration required. The old 9-parameter
function form remains callable via positional arguments.

Packaging note: There is no flat pgmnemo--0.11.0.sql. Fresh install resolves
via pgmnemo--0.10.1.sql (or earlier flat base) + delta auto-chain. The
INSTALLCHECK task owns verification of this path.

Fixed

• #84 — recall_fast NULL query_embedding silent score corruption. recall_fast(NULL::vector, ...) previously returned rows with score = NULL instead of raising an error. Now raises EXCEPTION P0001 with actionable message (use recall_hybrid() if you have query_text but no embedding). pg_regress T11 validates this guard. (cfdf8e3)

• #87 — recall_hybrid BM25 path timeout robustness (4 fixes). On large or Cyrillic-heavy corpora, recall_hybrid timed out on up to 20% of calls (p95 ≈ 910 ms). Four fixes applied in migration sections A–E:

  1. query_text capped to 200 chars before websearch_to_tsquery to prevent pathological parse cost
  2. Per-row to_tsvector(topic) removed — uses pre-computed indexed full_text column (GIN)
  3. BM25 block wrapped in BEGIN … EXCEPTION WHEN query_canceled with SET LOCAL statement_timeout = pgmnemo.bm25_budget_ms — timeout is a graceful fallback to vector-only, not a hard failure
  4. tsconfig changed from 'english' to 'simple' across all tsvector columns and query functions — correct tokenisation for Cyrillic and structured texts (no stemming, no stop-words)

  Measured result: 0% timeouts, p95 = 44 ms (20× improvement from 910 ms baseline). (a35c8fc)

Added

• pgmnemo.bm25_budget_ms GUC (INT, default 250, min 1). Controls per-query BM25 time budget in milliseconds. Set via SET pgmnemo.bm25_budget_ms = N or ALTER SYSTEM SET pgmnemo.bm25_budget_ms = N. Values below 50 ms may cause frequent graceful fallback to vector-only on large corpora.

• pg_regress tests: recall_hybrid_robustness (T1–T8 covering Cyrillic, >200-char cap, JSON/structured, graceful degrade, role_filter stable) and test_v0101 (T11 NULL guard + GUC assertable).

Migration notes

ALTER EXTENSION pgmnemo UPDATE TO '0.10.1' applies sections A–G of pgmnemo--0.10.0--0.10.1.sql. The migration changes GENERATED ALWAYS AS expressions for topic_tsv, lesson_tsv, and full_text columns from 'english' to 'simple' tsconfig. GIN indexes are rebuilt automatically; plan for brief I/O spike on corpora > 100k lessons.

Theme

Tiered-memory dispatch + recall_fast() + provenance-gate hardening + scale docs.
Adds per-content-type access-path routing (navigate_locate_dispatch), typed
dereference (navigate_expand_typed), selective-embedding backfill
(apply_selective_embedding_policy), and a new recall_fast() function for
pure HNSW vector recall at O(k log n). MCP pgmnemo.recall now routes to
recall_fast() by default; deep=true opts into recall_hybrid() for full
6-signal RRF fusion. Closes #80 (recall_fast), #81 (MCP filter params confirmed),
#82 (scale + SLO docs). Adds docs/AGENT_INTEGRATION.md (closes #79) and
confidence_boost_weight adoption guide.

Added

• pgmnemo.recall_fast(query_embedding, k, role_filter, project_id_filter, exclude_dag_id)
  Pure HNSW vector recall — ORDER BY embedding <=> query LIMIT k.
  No BM25, no graph BFS, no RRF, no recency weighting. score = cosine similarity.
  Return shape: 12-column (identical to recall_lessons() — MCP-compatible).
  Respects include_unverified, ef_search, track_recall_recency GUCs.
  Same filter surface as recall_hybrid: role_filter, project_id_filter,
  exclude_dag_id. Use when latency matters more than BM25/graph recall depth.

• pgmnemo.navigate_locate_dispatch(query_embedding, query_text, token_budget_chars, jsonb_filter, project_id_filter, content_type_dispatch)
  Routes each query to the cheapest adequate index per content_type_dispatch:
  'entity' → GIN BM25 on lesson_tsv; 'temporal' → btree on t_valid_from;
  'relation' → mem_edge BFS from BM25 seed; NULL → existing navigate_locate.
  Return schema identical to navigate_locate.

• pgmnemo.navigate_expand_typed(ids, graph_expand_depth, graph_expand_threshold, relation_types)
  Content-type-aware typed dereference:
  'entity' → metadata JSONB (canonical_name, entity_type) + connected lessons;
  'lesson' / NULL → full lesson_text (same as navigate_expand);
  'relation' → mem_edge neighbours only.

• pgmnemo.apply_selective_embedding_policy(p_dry_run)
  Sets embedding = NULL for non-semantic content types (entity, fact,
  relation, temporal) to reduce HNSW index noise.
  p_dry_run = TRUE (default) → preview only; FALSE → executes update.

• New indexes:
  ix_pgmnemo_lesson_tsv_entity (GIN on lesson_tsv WHERE content_type='entity');
  ix_pgmnemo_content_type_active (btree on content_type WHERE is_active);
  ix_pgmnemo_temporal_content_type (btree on t_valid_from WHERE content_type='temporal').

• docs/AGENT_INTEGRATION.md — dispatch guide, filter usage, tool whitelist,
  prefix convention (closes #79).

• Scale + Latency SLO section in docs/SQL_REFERENCE.md §6 — operational
  targets, index sizing guidance (closes #82).

• docs/CONFIDENCE_BOOST_GUIDE.md — step-by-step guide for activating
  reinforce() → confidence_boost_weight → ranking lift. Includes before/after
  SQL example and when-not-to-enable guidance.

• pg_regress coverage for provenance-gate moat (T1–T8): extension/sql/provenance_gate.sql.

Changed

• pgmnemo.recall MCP tool (pgmnemo-mcp v0.10.0):
  Default path changed from recall_lessons() → recall_fast()
  (pure HNSW, lower latency).
  New deep: bool = False parameter: when True, calls recall_hybrid()
  for full vector + BM25 + graph proximity + recency + confidence + provenance fusion.
  role_filter, project_id_filter, exclude_dag_id present in both paths.

• pgmnemo.get_params MCP tool: version string updated to "0.10.0".

Extension

Schema additions only — no existing function signatures changed. Upgrade is
non-breaking for all existing callers. Single upgrade delta: pgmnemo--0.9.7--0.10.0.sql.

Upgrade

ALTER EXTENSION pgmnemo UPDATE TO '0.10.0';

MCP server: pip install --upgrade pgmnemo-mcp==0.10.0.

Closes

• #80 — recall_fast() HNSW-only fast path with pg_regress coverage.
• #81 — role_filter / project_id_filter / exclude_dag_id in published
  MCP wheel confirmed by test_recall_exposes_filter_params in tests/test_mcp_smoke.py.
• #82 — Scale + SLO reference in docs/SQL_REFERENCE.md §6.
• #79 — docs/AGENT_INTEGRATION.md dispatch guide.

Theme

MCP params exposure + smoke-test validation.
Adds a new pgmnemo.get_params MCP tool that exposes current server configuration
(DATABASE_URL with masked password, embedding server, embedding model, embedding
dimension, MCP port) so AI clients can verify their connection without accessing
environment variables directly. Companion smoke tests validate all three MCP tools are
registered and functional.

Added

• pgmnemo.get_params MCP tool in pgmnemo_mcp. Returns database_url
  (password masked as ***), embedding_server, embedding_model,
  embedding_dim, mcp_port, and version. Allows MCP clients to verify server
  configuration without shell access.
• tests/test_mcp_smoke.py — 7-test smoke suite covering package import,
  __version__ assertion, tool registration (ingest / recall / get_params), unit-level
  DB call verification for ingest and recall, and get_params password masking.
• tests/conftest.py — shared pytest fixtures for smoke test suite.

Changed

• pgmnemo_mcp/__init__.py: exports get_params alongside ingest,
  recall, mcp, main. __version__ bumped to 0.9.7.
• pgmnemo_mcp/pyproject.toml: version 0.9.7; build system updated from
  hatchling to setuptools for compatibility.
• pgmnemo_mcp/tests/test_server.py: arg-index assertions updated to account for
  the embedding vector at position 5 (commit_sha → 6, artifact_hash → 7, metadata → 8
  for ingest; query_vec → 0, top_k → 1, query_text → 2 for recall).

Extension

No schema changes in v0.9.7. Extension default_version updated to 0.9.7; flat
install file pgmnemo--0.9.7.sql and delta pgmnemo--0.9.6--0.9.7.sql added
(no-op delta — schema unchanged from 0.9.6).

Upgrade

No schema changes — this upgrade is a no-op. MCP server: pip install --upgrade pgmnemo-mcp==0.9.7.

Theme

R11/R12/R13 — Versioned skill items, DAG-scoped recall, migration ingest log.
Three community requirements addressed in one schema release: content-type classification
for non-free-form lessons (item_kind), version tracking for evolving skills
(version_n, patch_count), workflow-origin tagging and exclusion (source_dag_id,
exclude_dag_id), and a migration helper table (memory_ingest_log) for operators
moving from legacy memory schemas.

Added

• item_kind TEXT NOT NULL DEFAULT 'note' on pgmnemo.agent_lesson.
  CHECK constraint: ('note','skill_md','template','script','reference','config','spec').
  Classifies lessons by content type; 'note' is the default for free-form lessons.
• version_n INT NOT NULL DEFAULT 1 on pgmnemo.agent_lesson.
  Monotonically increasing version counter. Increment when lesson_text is substantially
  revised (e.g. after a major update to a skill_md document).
• patch_count INT NOT NULL DEFAULT 0 on pgmnemo.agent_lesson.
  Minor patch edit counter. Reset to 0 on each version_n increment.
• source_dag_id TEXT NULL on pgmnemo.agent_lesson.
  Opaque identifier for the workflow/pipeline run that produced the lesson.
  NULL = unknown origin (manually ingested). Sparse index
  ix_pgmnemo_agent_lesson_source_dag_id covers non-NULL rows.
• exclude_dag_id TEXT DEFAULT NULL parameter on recall_hybrid() and
  recall_lessons(). When set, suppresses lessons whose source_dag_id matches the
  given value (IS DISTINCT FROM semantics: NULL source_dag_id rows always pass).
  Allows a workflow to exclude its own output from recall during the same run.
• pgmnemo.memory_ingest_log table. Tracks migration batches from legacy memory
  tables into pgmnemo.agent_lesson. Columns: id BIGSERIAL PK, source_origin TEXT,
  min_id BIGINT, max_id BIGINT, ingested_at TIMESTAMPTZ DEFAULT NOW(),
  retired_at TIMESTAMPTZ NULL. Operators drop it once the cutover window closes.
• extension/sql/versioned_items.sql — 5-topic pg_regress test file covering
  column defaults, CHECK enforcement, sparse index, memory_ingest_log CRUD, and
  exclude_dag_id filter semantics.

Changed

• recall_hybrid(): old 8-arg overload dropped; new 9-arg form adds exclude_dag_id TEXT DEFAULT NULL.
  Positional callers unaffected (DEFAULT NULL).
• recall_lessons(): old 6-arg overload dropped; new 7-arg form adds exclude_dag_id TEXT DEFAULT NULL.
  Positional callers unaffected (DEFAULT NULL).
• docs/SQL_REFERENCE.md: agent_lesson column table updated with four new columns;
  new §1.1 pgmnemo.memory_ingest_log table entry; recall_hybrid() and recall_lessons()
  signatures updated with exclude_dag_id parameter.
• docs/MIGRATION.md: new section "Legacy table migration via memory_ingest_log"
  with a worked example using INSERT INTO pgmnemo.agent_lesson ... SELECT ....

Breaking changes

recall_hybrid() and recall_lessons() drop their old fixed-arity overloads and
replace them with new overloads that add exclude_dag_id TEXT DEFAULT NULL as the
last parameter. Positional callers are unaffected — the new parameter defaults to
NULL. Callers that hold explicit GRANT EXECUTE on the old fixed-arity type signatures
(vector, TEXT, INT, TEXT, INT, DOUBLE PRECISION, DOUBLE PRECISION, INT and
vector, INT, TEXT, INT, TEXT, TIMESTAMPTZ) must re-apply grants to the new signatures.

Upgrade

ALTER EXTENSION pgmnemo UPDATE TO '0.9.6';

Adds four columns to pgmnemo.agent_lesson, one sparse index, and one new table.
Non-destructive; all existing rows receive default values. Estimated duration: <1 s on
any corpus size (no table rewrite).

Theme

E — Recall-recency signals + mark_stale(). Corpus of 6,584 lessons with
92 % never recalled could not be curated by actual use because last_recalled_at
didn't exist. This release adds the column, stamps it on every recall path, and
provides a safe, guarded curation primitive.

Added

• last_recalled_at TIMESTAMPTZ DEFAULT NULL on pgmnemo.agent_lesson.
  Stamped automatically by recall_hybrid(), recall_lessons(),
  navigate_locate(), and navigate_expand(). NULL = never recalled since
  v0.9.5 column addition.
• recall_count BIGINT NOT NULL DEFAULT 0 on pgmnemo.agent_lesson.
  Incremented once per recall-function call that returns the lesson. Monotonically
  increasing; never decremented.
• ix_pgmnemo_lesson_recall_recency partial index on (last_recalled_at ASC NULLS FIRST, created_at ASC) WHERE is_active — supports efficient stale-lesson
  scans.
• GUC pgmnemo.track_recall_recency (BOOLEAN, default on). When set to
  off, no stamping occurs and all four recall functions behave byte-identically
  to v0.9.4. Documented in SQL_REFERENCE.md §3.1.
• pgmnemo.mark_stale() — usage-based corpus curation primitive. Identifies
  and optionally deprecates lessons unused for p_unused_days (default 45 days).
  Safeguards prevent touching high-confidence (>= 0.6), high-importance (= 5),
  or provenance-bearing lessons. p_dry_run=TRUE (default) is read-only and safe
  to run anytime. p_cap (default 500) refuses to deprecate without explicit
  acknowledgement if candidates exceed the cap.
• extension/sql/recall_recency.sql — 9 pg_regress tests covering stamping,
  GUC control, dry-run, safeguards, and cap guard.

Changed

• recall_hybrid(), recall_lessons(), navigate_locate(),
  navigate_expand(): changed from STABLE → VOLATILE (required for the
  UPDATE side-effect in the data-modifying CTE stamp). No scoring change; existing
  query plans remain valid.
• docs/SQL_REFERENCE.md: new §3.1 row for pgmnemo.track_recall_recency;
  §3.6 entry for v0.9.5 new GUC. New mark_stale() entry in §2.
• docs/USAGE.md: new section "Usage-based curation — mark_stale()".

Upgrade

ALTER EXTENSION pgmnemo UPDATE TO '0.9.5';

Adds two columns to pgmnemo.agent_lesson and creates one partial index.
Non-destructive and backward-compatible. All recall function signatures unchanged.

Theme

Documentation-only release. No SQL changes. Covers three GUCs shipped in
v0.9.2–v0.9.3 that were missing from SQL_REFERENCE and USAGE:
confidence_boost_weight, reinforce_success_delta, reinforce_fail_delta.

Changed

• docs/SQL_REFERENCE.md: added confidence_boost_weight to §3.1 Recall scoring GUCs;
  new §3.3 Outcome-learning GUCs covering reinforce_success_delta and reinforce_fail_delta;
  §3.6 default-change history updated with v0.9.2–v0.9.3 entries.
• docs/USAGE.md: reinforce() section updated to reflect new default deltas
  (+0.02/−0.12); GUC override example added.
• CHANGELOG.md: [0.9.2] entry annotated — no separate git tag, shipped as part of v0.9.3.

Upgrade

ALTER EXTENSION pgmnemo UPDATE TO '0.9.4';

No-op — schema unchanged. Safe to run at any time.