Skip to content

fix(memory): keep exported semantic vectors through memory import - #25775

Merged
iamwhatever merged 1 commit into
mainfrom
fix/import-semantic-vectors-9732
Oct 29, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/import-semantic-vectors-9732

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: after kirocrew memory export and kirocrew memory import, semantic rows are vector-searchable at once instead of keyword-only.

import_memory writes every semantic row with no vector. The CLI store has no embedder, so the row's own embed tail never runs, and memory export writes each stored vector BLOB through json.dumps(..., default=str), which produces a bytes repr that nothing can read back.

Why it matters

After a restore, recall over the imported facts silently finds nothing by meaning until a gateway boot sweep re-embeds them, and the import summary does not say so for semantic rows. The export file also carries a large unreadable string per row.

Not a goal

  • Episodic vectors. The export does not ship them today and this change does not add them; imported episodes still land without a vector on the CLI path and the existing import note covers them. Shipping them adds up to ~55 MB to the default export at the 10,000-episode cap, which is a payload-size decision this bugfix does not make.
  • Carrying vectors across different models or widths. Signatures exist to forbid that.
  • Any change to the dashboard import (POST /api/memory/import): its store has an embedder and keeps embedding rows itself.

Intended? / Repro

Intended? No. The issue describes the import as asymmetric by accident, and the CLI's own note (_IMPORT_EMBED_NOTE in src/kiro_crew/cli_commands_memory.py) treats a vector-less import as a gap to warn about, not a design. The write path already accepts a resolved vector (set_semantic(..., embedding=, embedding_resolved=, embedding_generation=), added for pre-embedding callers), so nothing forbids carrying one.

Repro (read on current main 6b5bedad1b):

  • src/kiro_crew/vector_memory_runtime/bulk_ingest.py:175: self.set_semantic(entry["key"], val, conf, src) passes no vector, while the episodic branch at :185 passes embedding=self._try_embed(...).
  • src/kiro_crew/vector_memory_runtime/semantic.py:1368: the semantic write tail embeds only when store.embed_fn is not None; the CLI store has none, so the row stays NULL.
  • src/kiro_crew/cli_commands_memory.py:1089 exports store.get_all_semantic() (which includes the embedding BLOB) and :1098 serializes it with default=str.
  • The issue's 0.5.0 run: 656 semantic entries imported, 2 with an embedding afterwards (SELECT count(*), sum(embedding IS NOT NULL) FROM semantic_memory WHERE is_deleted=0).

What changed (motivation → approach → change)

Symptom: imported semantic rows have no vector. Cause: the export's vector is unreadable and the import never passes one. Change: export a readable vector plus the model it came from, and let the import keep it only where that model is provably the one this store uses.

  • Export (cli_commands_memory.py): each semantic row's vector BLOB ships as base64 of its float32 bytes. When at least one ships, the payload ends with embedding_space_sig and embedding_model: {"model_id", "dim"} (bulk_ingest.export_embedding_space). The model is named only when this process can produce the signature from a model id and width: the bundled model (the owner of any unrecorded space) or the active backend (metadata only, no model load); otherwise null. The signature is read before and after the row read, and both keys are null if a model swap committed in between. A payload with no vectors keeps its previous shape byte for byte.
  • Import (bulk_ingest.import_memory): a row's vector is persisted as it is only when _payload_space_carryable holds: the store has no embedder; the payload names its model; that model and width produce the payload's signature; the width matches the store; and the signature equals both the store's recorded space (unrecorded counts as the bundled model's, as in store_embedding_space_is_stale) and the active backend's, with no pending rebuild. Each vector must decode to exactly dim finite float32 values, so a legacy repr string, a wrong width or a NaN is dropped and that row lands NULL as before. The vector is wrapped in _EmbeddingVector with the store's space token read at the decision, so the publish transaction (_vector_commit / _embedding_current) drops it if a reconcile lands before it commits. A store with an embedder ignores payload vectors and embeds the row's own text.
  • CLI note: the existing "embedding vectors are not built by this command" note now also prints when only semantic rows were imported and some still lack a vector.
  • docs/system-specs/modules/cli.md: the export/import row describes the vector fields and the carry rule.

Review item from #10388 (iamwhatever, CHANGES_REQUESTED)

should we also export the model id as well? ... so the import side can do verification.

Addressed: the export ships embedding_model: {"model_id", "dim"} beside embedding_space_sig, and the import requires it. A payload without a model, or whose model does not produce its own signature, carries no vectors (tests no-model, model-not-matching-signature, bool-dim).

Security

The payload is user-supplied input. A carried vector is only accepted at the store's exact width, as finite float32 values, under a signature that must match the store and the active backend, and only on a store that cannot compute the vector itself. The worst a hand-edited payload can do is mis-rank its own imported rows; row text and keyword search are unaffected, and a dashboard (embedder-backed) import never trusts payload vectors. No new endpoint, file path or permission.

Backwards compatibility

  • Old payload, new importer: no embedding_model, so nothing is carried and rows land NULL as before.
  • New payload, old importer: two extra top-level keys and string embedding fields, which the old importer ignores.
  • A payload with no vectors is byte-identical to main (the default-shape guard in test/test_memory_markdown_read.py is unchanged; its stub gains recorded_embedding_space).

Removes nothing: no key, field or error path is removed. The semantic embedding field changes from an unreadable repr string to base64.

Tests

  • test/test_vector_memory_coverage.py::TestImportCarriesExportedVectors
    • test_vector_from_the_same_model_is_persisted: the exact float32 vector lands in semantic_memory.embedding. On main it is NULL.
    • test_unusable_vector_imports_the_row_without_it (no model, model not matching the signature, bool dim, foreign space, legacy repr, wrong width, non-finite): row imported, vector NULL.
    • test_model_swap_during_the_space_check_drops_the_vector: a reconcile landing while the space is judged leaves the row NULL, because the space token is read once before the check and the commit re-checks it.
    • test_store_in_another_space_does_not_take_the_vector: an unrecorded (bundled) store refuses a custom-model payload.
    • test_store_with_an_embedder_embeds_the_row_itself: the store's own vector wins.
    • test_export_names_the_model_of_its_vectors, test_unrecorded_store_exports_the_bundled_model.
  • test/test_cli_commands_coverage_memory_eval.py: export ships base64 plus the two keys last; both keys null when the space changed during the read; the import note prints for semantic-only imports.

Proof: not provable -- other: this host runs no local tests; CI runs the new tests

Manual verification

N/A: no UI. Static gates run locally: black (diff region), isort, flake8, scripts/check_file_line_cap.py, scripts/docs_lint.py, scripts/check_comment_history.py with COMMENT_HISTORY_BASE_REF=origin/main. Tests run in CI.

Why no screenshot: CLI and storage change only; no dashboard or website file is touched.

Related Issues

Fixes #9732

Supersedes #10388. That PR predates the split of vector_memory.py into vector_memory_runtime/* and also changed episodic export, streaming and --no-vectors; this one is the smallest fix on current main.

Sibling sweep

Swept: git grep -n -E "import_memory(|default=str" -- src/kiro_crew
Sibling: src/kiro_crew/cli_commands_memory.py -- changed here (the only export that serializes vector BLOBs)
Sibling: src/kiro_crew/dashboard/handlers/memory.py -- not affected (its store has an embedder, so it embeds each row itself)

Pattern harvest

Rule candidate: a value restored from an export may be trusted only where it cannot be recomputed and its provenance (here, model id + width → signature) matches the destination exactly; carry the destination's state token with it so the commit re-checks the match under its own lock.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 2a85be522e25244c49689b9499cad3986aad79a5 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 2a85be522e25244c49689b9499cad3986aad79a5 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The import keeps a vector only when the payload names its model, that model produces the payload's signature, and the signature matches the store and the active backend. Any other row lands without a vector, as it does today.

Notes

  • Only the semantic embedding field changes, from an unreadable bytes repr to base64. I found no reader of the old repr outside the patch, and the dashboard import ignores payload vectors because its store has an embedder.

[DESIGN-REVIEWED] 2a85be5

Description read

[DESCRIPTION-READ] 725d77fb09f9a7950e421362d462087dc238b1828ae3bdfb4add4ffb7e3bd040

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 2a85be522e25244c49689b9499cad3986aad79a5 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. One payload key repeats what the signature already proves.

Notes

  • Item 3 — inherited: its only support is a reviewer's question on fix(memory): carry semantic embeddings through export/import (#9732) #10388 ("should we also export the model id as well?"). The signature is sha256(f"{model_id}|{dim}") (embeddings_shared.py:207). The import already requires signature == recorded and signature == active_embedding_space_signature(), so the model and width are already proven before the embedding_model checks run. Yet a payload whose model the exporter cannot name (None) carries no vectors, so the extra key turns away exports that are otherwise valid. Subtraction: delete the embedding_model key, the model_id/model_dim checks in _payload_space_carryable, and the get_shared_embedder branch of export_embedding_space; gate on embedding_space_sig alone.

What this change ships

Inventory (8 items) — 7 justified

Intent: after a CLI memory export and import, imported facts can be found by meaning straight away, not only by keyword. FIX (#9732).

  1. Exported semantic vectors are now readable base64 instead of a bytes repr — justified
  2. Export gains a top-level embedding_space_sig when any vector ships — justified
  3. Export gains a top-level embedding_model {model_id, dim} — duplicate of the signature check
  4. Both space keys export as null if a model swap lands during the row read — justified
  5. CLI import keeps an exported vector when the store, the payload and the active backend all share one space — justified
  6. A malformed, wrong-width, non-finite or foreign-space vector is dropped and the row imports with no vector — justified
  7. The "vectors not built" import note now also prints for imports with only semantic rows — justified
  8. The export/import row in cli.md now describes the vector fields and when a vector is kept — justified

[FIRST-PRINCIPLES-REVIEWED] 2a85be5

Description read

[DESCRIPTION-READ] b34cb5c1345ff09aff55a4c0e5b34f1a59b6dffcd6ffefaef8ee5d4d977c097f

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 2a85be522e25244c49689b9499cad3986aad79a5 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 2a85be5

Verdict parsed from the review's SHA-scoped output markers for commit 2a85be522e25244c49689b9499cad3986aad79a5.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 2a85be522e25244c49689b9499cad3986aad79a5 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 2a85be522e25244c49689b9499cad3986aad79a5 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2a85be5

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 2a85be522e25244c49689b9499cad3986aad79a5 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 29, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/import-semantic-vectors-9732 branch from 6bb8e8f to 9201905 Compare October 29, 2026 13:45
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 29, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/import-semantic-vectors-9732 branch from 9201905 to 2a85be5 Compare October 29, 2026 14:47
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 29, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve at 2a85be5.

The import keeps an exported vector only on a store that cannot compute it, only when the payload's model and width produce its signature, and only when that signature matches both the store and the active backend (bulk_ingest.py#L70-L110). Each vector must decode to exactly dim finite floats (#L113-L126), and the space token travels with it, so a reconcile before commit drops it. Anything else lands without a vector, as it does on main. Every AI lane passes; the cancelled check runs are superseded by newer successes; PR Readiness is green.

AI findings judged non-blocking

  • First Principles: embedding_model repeats what the signature proves. It only makes the carry rule stricter; a refused payload falls back to today's behaviour, and the key was asked for on #10388 (bulk_ingest.py#L43-L67).

— crew-pr-reviewer (r135)

@iamwhatever
iamwhatever enabled auto-merge (squash) October 29, 2026 16:42
@iamwhatever
iamwhatever merged commit 4d36177 into main Oct 29, 2026
97 of 105 checks passed
@iamwhatever
iamwhatever deleted the fix/import-semantic-vectors-9732 branch October 29, 2026 16:45
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 29, 2026
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.

memory: kirocrew memory import leaves semantic entries unembedded (import re-embeds episodic but not semantic)

2 participants