Repository navigation
Knowledge memory: faster knowledge turns, per-space knowledge cards, portal status fixes - #475
Merged
Merged
Conversation
…, 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
Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01W9t7FdL2v5fh7touPfWzqC
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Portal status fixes
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_conditions()is shared with the admin statistics.Faster knowledge turns (ADR-0009 §10d)
timings_msgainsprepare_context_ms. On the streaming route it also gainsttft_ms, the time to the first answer delta, measured on any path.POST /api/v1/memorywithinclude_chunksembeds 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)
memory_cards_enabledlives 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.llmmode, in a newknowledge_cardstable: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.Affected services
services/ingest (backend + portal frontend), services/knowledge, services/retrieval, services/runtime, contracts/ (
chunk-store.md,internal-chat.md,openapi.json), docs/adr/0009Migrations: ingest
0064_memory_cards, knowledge0008_knowledge_cards. Knowledge 0008 should roll out before the new Runtime; without it Retrieval serves no cards and everything else keeps working.Test plan
tsc --noEmitclean, vitest 409 passedef_search), parallel fulltext leg under concurrent load. All automated tests ran on SQLite.llmmode and check that cards appear after the next memory run and in the chat trace (memory_ms,ttft_ms,prepare_context_ms)Checklist
contracts/updated if an API or event changed (openapi.jsonregenerated)python scripts/weave_config.py checkpasses if configuration changed. Not checked: it needs a realdeploy/.env, which this environment lacks (it only reports missing required secrets).docs/updated if operators or users see the change (ADR-0009 §10d, §13)deploy/.envin the diffNotes for reviewers
EMBEDDING_QUERY_CACHE_SIZE,EMBEDDING_QUERY_CACHE_TTL_SECONDS,SEARCH_PARALLEL_LEGS,SEARCH_PARALLEL_WAIT_SECONDS,MEMORY_CARD_MIN_SIMILARITYRETRIEVAL_MEMORY_TIMEOUT_SECONDS.env.example.memory_msis now the wall clock of the combined memory + search call. The per-step times are inRetrievalTrace.search.timings_ms.Generated by Claude Code