Recover a debugging solution: retrieve, read, then verify reuse

Remembering that you solved a problem without remembering its conditions and changes is more troublesome than losing a code snippet. A knowledge base can narrow the search, but a related note still needs a check against the current situation.

The following is a constructed scenario: a React page issues duplicate requests, and a historical note records an investigation. It is not a personal incident or a measured promise of retrieval within a few seconds. Behavior follows the search routes and note services in ChatCrystal at commit 7642768.

Establish that a searchable note exists

Importing conversations, generating notes, and creating vectors are separate steps. Current semantic retrieval searches note vectors; absent notes do not trigger fallback to full-text search over original conversations. Select an actual conversation outside the demo data and complete the summary and index steps in the getting-started workflow.

crystal --json notes list --limit 20

Select the known note’s ID from items, then read its details:

crystal --json notes get <note-id>

Check its content and embedding_status. done means vector processing completed, not that the summary is necessarily correct. Resolve pending, syncing, or failed index states first. The experience gate can also legitimately filter a conversation without generating a note. See LLM and embedding responsibilities for model configuration and rebuilding acceptance.

Describe the problem, then compare phrasing

With the default local connection, use JSON output to pass the requested limit to retrieval. Fewer eligible candidates can produce fewer results than this upper bound:

crystal --json search "React page sends duplicate requests; how to locate the trigger" --limit 5

Keep distinguishing conditions: stack, error, stage, and expected behavior. Try short keywords too. Natural language does not always outperform keywords, and longer descriptions can introduce irrelevant concepts. Checking whether several phrasings retrieve the same known note is more testable than claiming that specificity always improves accuracy.

The search route returns candidate fields including note_id, conversation_id, title, project, tags, and score. It does not directly return full note bodies or original conversation excerpts. CLI JSON is an unwrapped array. If jq is installed, extract identifiers with:

crystal --json search "React duplicate requests" --limit 5 |
  jq '.[] | {note_id, conversation_id, title, score}'

Use .[], not .data[]. Results are entrances to further reading, not verified debugging answers.

Read the note and return to the original record

Fetch details using the candidate’s note_id. Inspect the problem, conclusions, snippets, and project. A summary can omit environmental conditions; when needed, use conversation_id with GET /api/conversations/<id> to inspect actual messages.

In this constructed scenario, ask whether duplicates occurred in development or production; whether they came from lifecycle behavior, user events, or retries; and whether the historical change removed the fault or concealed its symptoms. Do not apply a particular React setting without evidence.

The retrieval implementation combines vector candidates, lexical boosts, and note deduplication. Its score is neither a pure raw cosine value nor a probability that a solution is correct. Higher scores help prioritize reading.

Test recovery with positive and negative queries

Record at least two query types: a problem that should retrieve the known solution, and one for which the knowledge base has no relevant answer. For the positive case, check candidate inclusion and whether the note explains the handling. For the negative case, inspect empty results or candidates that require human rejection.

If nothing appears, check whether the real note exists, vector processing completed, the query model matches stored vectors, and the wording relates to the content. An empty result does not directly prove poor model quality. Summarizing an existing note’s conversation does not automatically rewrite that note either: the current summary service returns its existing ID first. summarize --all is not whole-library regeneration.

Verify the current project before reuse

Turn the historical solution into a testable hypothesis. Reproduce the issue in the current project, apply a minimal change, and check the fault plus relevant regression paths. Recheck official references when versions, dependencies, or deployment conditions differ.

Only after examining applicability and results does a candidate become evidence for the current task. If an Agent retrieves through MCP, ask it to show the note, conditions, and validation steps; supplying a tool does not guarantee automatic invocation every time. See RAG and knowledge graphs for retrieval and relation boundaries, and the knowledge memory loop for writeback quality.