Skip to content

Knowledge memory: faster knowledge turns, per-space knowledge cards, portal status fixes - #475

Merged
bl0rb merged 5 commits into
mainfrom
claude/dazzling-lamport-kbgqjw
Nov 19, 2026
Merged

bl0rb merged 5 commits into
mainfrom
claude/dazzling-lamport-kbgqjw

Conversation

@bl0rb

@bl0rb bl0rb commented Nov 19, 2026

Copy link
Copy Markdown
Owner

Summary

Portal status fixes

  • Releases that a newer version replaced (Knowledge state superseded) no longer count as "indexing" on the knowledge space card. The documents status filter gets its own "Replaced by a newer version" option.
  • "In chat" (list filter, count, per-space stat) excludes superseded and withdrawn releases. The rule in_chat_conditions() is shared with the admin statistics.

Faster knowledge turns (ADR-0009 §10d)

  • Measurement: timings_ms gains prepare_context_ms. On the streaming route it also gains ttft_ms, the time to the first answer delta, measured on any path.
  • Retrieval quick wins:
    • The memory's ranking search runs without rerank, with a pool of 20 and without its own control-plane refresh.
    • An in-process query-embedding cache (LRU 512, TTL 600 s).
    • The fulltext leg runs on a second session in parallel with embedding and vector search. It only starts when the pool has a free connection and is waited for at most 2 s.
  • One call instead of two: POST /api/v1/memory with include_chunks embeds once and returns the focused search, or the plain fallback search. Runtime uses it and keeps the two-call path for an older Retrieval. The combined call gets its own timeout, twice the search timeout by default.

Knowledge cards per knowledge space (ADR-0009 §13)

  • The switch memory_cards_enabled lives in the portal's space editor. It is owner-only and off by default. It flows from Ingest to Knowledge through the registry sync; a missing field means off.
  • Knowledge builds up to 5 question/answer cards per document, only in llm mode, in a new knowledge_cards table:
    • identical cards are deduplicated;
    • cards are rebuilt when the source changes;
    • when a primary source goes away, the card is handed to the next remaining source instead of being rebuilt;
    • cards are deleted on switch-off or space removal.
  • Retrieval serves cards through apply_filters() and drops a card unless all its sources are visible. Card search runs in a savepoint, so any failure serves no cards instead of failing the request.
  • Runtime shows cards only in the non-citable orientation block. Sources stay chunks only.

Affected services

services/ingest (backend + portal frontend), services/knowledge, services/retrieval, services/runtime, contracts/ (chunk-store.md, internal-chat.md, openapi.json), docs/adr/0009

Migrations: ingest 0064_memory_cards, knowledge 0008_knowledge_cards. Knowledge 0008 should roll out before the new Runtime; without it Retrieval serves no cards and everything else keeps working.

Test plan

  • Runtime backend: full suite, 711 passed
  • Retrieval backend: full suite, 286 passed (3 consecutive runs)
  • Knowledge backend: full suite, 442 passed
  • Ingest backend: collections, migrations, backup, portal and document freshness suites, 127 passed
  • Ingest frontend: tsc --noEmit clean, vitest 409 passed
  • Postgres: migrations 0064/0008 against a real database, pgvector card search (HNSW iterative scan / ef_search), parallel fulltext leg under concurrent load. All automated tests ran on SQLite.
  • Manual: switch cards on for one space in llm mode and check that cards appear after the next memory run and in the chat trace (memory_ms, ttft_ms, prepare_context_ms)

Checklist

  • Tests added or updated for the changed behaviour
  • contracts/ updated if an API or event changed (openapi.json regenerated)
  • python scripts/weave_config.py check passes if configuration changed. Not checked: it needs a real deploy/.env, which this environment lacks (it only reports missing required secrets).
  • Docs in docs/ updated if operators or users see the change (ADR-0009 §10d, §13)
  • No secrets, real customer data, or generated deploy/.env in the diff

Notes for reviewers

  • New optional settings (defaults in code):
    • Retrieval: EMBEDDING_QUERY_CACHE_SIZE, EMBEDDING_QUERY_CACHE_TTL_SECONDS, SEARCH_PARALLEL_LEGS, SEARCH_PARALLEL_WAIT_SECONDS, MEMORY_CARD_MIN_SIMILARITY
    • Runtime: RETRIEVAL_MEMORY_TIMEOUT_SECONDS
    • They are not yet listed in .env.example.
  • The "New knowledge space" dialog has no card switch yet; it is only in the edit dialog.
  • memory_ms is now the wall clock of the combined memory + search call. The per-step times are in RetrievalTrace.search.timings_ms.

Generated by Claude Code

…, not indexing

pipelineStage fell through to 'indexing' for Knowledge's 'superseded'
state, so the knowledge space card showed e.g. "12 indexing" and the
documents status filter "Indexing" listed old versions. Superseded is now
its own stage: no chip on the space card, its own status filter option.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01W9t7FdL2v5fh7touPfWzqC
The portal's in_chat filter, its count and the per-space stat counted every
release with status 'sent', including versions replaced by a later released
version (Knowledge: 'superseded') and withdrawn ones. They now share
document_freshness.in_chat_conditions() with the admin statistics, which
already applied that rule (superseded_by_release moved there from
admin_statistics.py).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01W9t7FdL2v5fh7touPfWzqC
Measurement (runtime): timings_ms gains prepare_context_ms and, on the
streaming route, ttft_ms (first answer delta on any path).

Retrieval quick wins: the memory's ranking search runs without rerank,
with a pool of 20 and without its own control-plane refresh; an
in-process query-embedding cache (LRU 512 / TTL 600 s); the fulltext leg
runs on a second session in parallel with embedding and vector search.

One call instead of two (ADR-0009 §10d): POST /api/v1/memory with
include_chunks embeds once and returns the focused (or fallback) search;
runtime uses it and keeps the two-call path for an older Retrieval.

Knowledge cards (ADR-0009 §13): per knowledge space, switchable in the
portal (memory_cards_enabled, default off, Ingest -> Knowledge registry
sync). Knowledge builds up to 5 question/answer cards per document in llm
mode (dedup, rebuild on change, delete on withdrawal/switch-off), table
knowledge_cards. Retrieval serves them via include_cards through
apply_filters with a fail-closed source check; runtime shows them in the
non-citable orientation block and adds their sources to the focus.

Migrations: ingest 0064_memory_cards, knowledge 0008_knowledge_cards.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01W9t7FdL2v5fh7touPfWzqC
- Knowledge: a card whose primary document changes, is withdrawn or is
  no longer indexed goes to its next remaining source instead of being
  deleted and rebuilt by the other sources (two documents sharing facts
  rebuilt each other forever). Withdrawal also removes the document from
  cards where it is a secondary source.
- Knowledge reindex: a card embedding failure no longer fails the chunks'
  re-embedding; the cards are rebuilt instead.
- Retrieval: the parallel fulltext leg only starts when the pool has a
  free connection and is waited for at most SEARCH_PARALLEL_WAIT_SECONDS.
- Retrieval: card search widens the HNSW scan (iterative scan, else
  ef_search) inside a savepoint that is rolled back, and any card error
  (not only SQL) serves no cards instead of failing the request.
- Runtime: the combined memory call gets its own timeout
  (RETRIEVAL_MEMORY_TIMEOUT_SECONDS, default twice the search timeout).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01W9t7FdL2v5fh7touPfWzqC
@bl0rb
bl0rb merged commit 00e8441 into main Nov 19, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants