Skip to content

refactor(vector_memory_runtime): reuse store helpers, drop a dead guard - #23744

Merged
bolichen97 merged 1 commit into
mainfrom
refactor/simplify-vector_memory_runtime
Oct 24, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
refactor/simplify-vector_memory_runtime

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make three spots in src/kiro_crew/vector_memory_runtime/ read as what they are, reusing the store's own helpers and dropping a guard that never fires, and correct one false comment, with no change in what the memory store stores, returns or logs.

Three spots in the vector-memory owners say more than the code needs to:

  • faiss_index.save_faiss_index hand-writes the memory_meta upsert that the store's _write_meta_in_transaction already owns.
  • write_lesson restates embed_lesson's one-line body.
  • store_bookkeeping._ineligible_ids guards against an empty chunk that its own loop can never produce.

The comment on write_lesson's contains branch also says the branch logs "like the siblings do". In fact it logs nothing, and neither do the two branches beside it.

Why it matters

Nothing is broken today. A hand-written copy of a helper is a second place to update when the upsert changes. An inline embed that restates embed_lesson lets a pre-embedded rule (callers pass one in) and the one write_lesson computes itself drift apart. A comment that names a log call the code does not have sends the next reader looking for one. Each of these is a small cost every time someone reads this lesson-writing and FAISS-stamping code.

Not a goal

  • Any change to what the store writes, deletes, returns, logs or hashes.
  • The other leads seen in this package, in files no structural edit here touches: stale comments in embedding.py, embedding_repair.py, semantic.py, lessons.py, episodic_write.py, and the four-level nest in write_lesson's pre-pass. The last one sits next to hunks that open PR feat(overview): add search and inline editing to lessons table (#17982) #18831 inserts.
  • VectorMemoryStore._cosine_sim: no source code calls it, but tests and the composition contract pin it.
  • lesson_write.py's other comment that the lexical branches "supersede the stored row unconditionally", which reads oddly next to may_retire_existing.

What changed (motivation → approach → change)

The memory store behaves as before. Each spot now reuses the code that already owns the job, or loses a line that cannot run:

Where Before After
faiss_index.save_faiss_index its own INSERT ... ON CONFLICT into memory_meta store._write_meta_in_transaction("faiss_content_signature", stamp): the same upsert, clock (vector_memory._now_iso, read at call time) and open BEGIN IMMEDIATE transaction. The helper re-takes _db_lock, a threading.RLock the caller already holds, and does not commit
write_lesson self._try_embed(rule) if self.embed_fn else None self.embed_lesson(rule), whose body is exactly that expression
store_bookkeeping._ineligible_ids if not chunk: continue removed: every start range(0, len(unique), _MAX_SQL_PARAMS) yields is below len(unique), so every slice holds at least one id

The contains-branch comment now says what all three queueing branches do: each deletes nothing, at most queues a supersede, and the drain after set_semantic logs each queued row it retires or skips. The old comment's rationale for logging keys rather than row text moves to the drain, where the log lines are, restated for what holds there.

Only a patch tells the old and new forms apart. A class- or instance-level patch of _write_meta_in_transaction or embed_lesson now reaches these two call sites. No test in test/ patches either in a way whose outcome changes.

Backwards compatibility

Compatible: no signature, return value, SQL effect, log line or import changes; the AST differs from origin/main only at the three code sites above.

Removes nothing: the deleted guard could never fire, the deleted upsert and embed expressions are the bodies of the helpers now called, and the comment edits change no code.

Tests

  • No test added or changed. Existing tests already pin each changed line. A mutation run on the related set:
    • Dropping the stamp write, or renaming its key, reds test_vector_memory_composition_contract.py::TestFaissAccelerator::test_save_then_load_round_trips_the_stamped_index.
    • Replacing the embed with None reds test_vector_memory.py::TestValueSizeLimit::test_non_ascii_lesson_embedding_is_persisted and test_vector_memory_embedding_lifecycle.py::TestSemanticWriteTimeEmbedding::test_lesson_write_keeps_raw_rule_vector.
    • The removed guard has no mutant, since it never runs.
  • Related tests (Python 3.12). 108 files that reference the changed functions, plus every test_vector_memory*, test_lesson* and test_embedding* file: 5602 passed, 0 failed. This run adds a markdown-it-py overlay, which the host venv lacks. Without the overlay, 18 files fail identically on origin/main and the branch. A serial coverage run executes all three changed code lines.
  • Static gates (Python 3.12). All exit 0 on the rebased commit:
    • flake8, isort and mypy.
    • The black, subprocess-encoding, comment-history, brand, harness-parity, feature-map, line-cap and memory-store-seam checks.
    • The loop-bound-locks, sync-io-in-async, cwd-relative-reads, agent-SDK-boundary, ACP-frame and testpaths checks.
    • The docs lint (scripts/docs_lint.py --test, scripts/docs-lint.sh), the per-file coverage self-test, the --test self-tests, the flake-pattern ratchet and the vendor manifest.
  • Pre-PR review. Seven read-only reviewers looked at the change: repo rules, behaviour, import and binding, security and boot path, claim accuracy, and local mirrors of the Opus and GPT lanes. The GPT mirror ran on a Claude model.
    • Code: no defect found. The behaviour reviewer found base and head ASTs differ only at the three code sites. Probes of both trees gave identical results apart from the upsert's SQL whitespace. The security reviewer found that no changed file is keystone and no guard, audit, redaction or log call changed.
    • Wording: six Low findings, all on the comment and commit wording this PR adds. Two adjudicators upheld four of them. They split on whether "IDENTITIES only" overstates and on the tense of a CodeQL sentence; this text takes the more conservative wording for both. Both rated "the read path redacts it" false, because kirocrew learn list prints lesson text unredacted, so that sentence is gone. One reviewer's request to restore "redacted at every surface" and "may reach a notification channel" was dropped, as neither holds.
  • Not run locally. scripts/scrub-lint.sh is absent from the checkout (CI's internal-content-scan covers it). semgrep is not installed on this host (CI's SAST job runs semgrep/). The frontend did not run, as nothing under website/, .github/ or scripts/ changed.

Manual verification

N/A: the related tests execute every changed code line, and the mutation run shows they fail when those lines change. A head-vs-base probe compared the memory_meta row, the statement order, lesson outcomes and _ineligible_ids results over chunk sizes 1-500 and found them identical apart from SQL whitespace.

Screenshots / video

Why no screenshot: backend-only refactor; no page, card or string changes.

Related Issues

Part of #16523

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; see the Licensing section of CONTRIBUTING.md.

Three behaviour-preserving simplifications in the vector-memory owners,
plus one false comment:

- faiss_index.save_faiss_index stamps memory_meta through the store's
  own _write_meta_in_transaction instead of a hand-written copy of the
  same upsert. The same upsert, clock and open transaction; the helper
  re-takes the store's RLock, which the caller already holds.
- write_lesson embeds its rule through embed_lesson, the method callers
  use to embed a rule ahead of the call, instead of restating its body.
- store_bookkeeping._ineligible_ids drops an `if not chunk: continue`
  that cannot fire: every start the range yields is below len(unique),
  so every slice holds at least one id.
- The comment on write_lesson's contains branch said the branch logs
  "like the siblings do". It logs nothing and neither do the topic or
  semantic branches: each at most queues a supersede, and the drain
  after set_semantic logs each queued row it retires or skips. The
  comment now says that, and its rationale for logging keys rather
  than row text moves to the drain, where the log lines are, restated
  for what holds there.
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 24, 2026 13:54
@bolichen97
bolichen97 requested a review from CrysisDeu October 24, 2026 13:54
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 798f437d7b4341b3dad184f4a801fac94f15e19d 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 added the readiness: checking Automated validation is still running label Oct 24, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns. Both new calls go to helpers whose bodies match the code they replace, and the removed guard can never run.

[DESIGN-REVIEWED] 798f437

Description read

[DESCRIPTION-READ] 4ba815e4d1a8867c21556555692564e1a9a26b5f83323955728398e75bdf48e5

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 798f437d7b4341b3dad184f4a801fac94f15e19d — 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 to check.

What this change ships

Inventory (4 items) — 4 justified

Intent: make the vector-memory code reuse the store's own helpers and correct a false comment, with no change in behaviour. This is a FIX (a cleanup refactor).

  1. The FAISS save writes its index stamp through the store's existing metadata helper (store_bookkeeping._write_meta_in_transaction) instead of its own copy of the SQL — justified
  2. Lesson writing calls embed_lesson instead of repeating that function's one-line body — justified
  3. A guard against an empty chunk is removed from the ineligible-id lookup, since the loop can never produce one — justified
  4. The comment that said the contains branch logs was false and is corrected; the reason for logging keys rather than lesson text moves to the drain, where the log lines are — justified

[FIRST-PRINCIPLES-REVIEWED] 798f437

Description read

[DESCRIPTION-READ] 0215f6d5f99e0cc7e882b3c8af83e4d9c06bff0222c8fe465ba48a0464cf03e2

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 798f437d7b4341b3dad184f4a801fac94f15e19d — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 798f437

Verdict parsed from the review's SHA-scoped output markers for commit 798f437d7b4341b3dad184f4a801fac94f15e19d.

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

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 798f437d7b4341b3dad184f4a801fac94f15e19d and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 798f437

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

@bolichen97
bolichen97 enabled auto-merge (squash) October 24, 2026 14:05
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 24, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Tier 1 auto-approve: refactor (3 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: code-move only in vector_memory_runtime; the inline memory_meta upsert is replaced by the existing _write_meta_in_transaction helper with the same SQL, the inline embed is replaced by embed_lesson with the same expression, and the removed empty-chunk guard is unreachable because the range step never yields an empty slice; the rest is comment text.

@bolichen97
bolichen97 merged commit 49f7ade into main Oct 24, 2026
106 checks passed
@bolichen97
bolichen97 deleted the refactor/simplify-vector_memory_runtime branch October 24, 2026 15:22
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 24, 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.

2 participants