Context Mode
A safe Context Mode quickstart: index a release note and verify retrieval
Use explicit ctx_index and ctx_search calls with invented release notes, known answers and a missing-fact check before connecting real project data.
What you will learn
- Use invented content with known answers before real data.
- Search with a distinctive source label and inspect the passage.
- Missing facts must remain unknown.
Before you start
- Basic JSON and MCP concepts
- An isolated test client and invented data
Explain the chapter’s actual implementation boundary and verify it with an explicit evidence fixture.
Key takeaways
- Use invented content with known answers before real data.
- Search with a distinctive source label and inspect the passage.
- Missing facts must remain unknown.
Use an already configured, isolated integration
Start with a test host in which Context Mode tools are registered; the deployment chapter explains the installation boundary. Do not begin by indexing your home directory, credentials or a production log archive. The sample below is an invented release note that contains a distinct release label, a timeout and a rollback condition. None of those values describes a real service.
Pass the note as content to ctx_index with a distinctive source label. The inspected schema accepts content or path, not both, and the tool returns indexing metadata rather than echoing the whole document. Save that metadata. Re-indexing is not advertised as idempotent, so repeatedly submitting the same sample is not a reliable way to test a clean database or deduplication.
Ask questions whose answers you already know
Call ctx_search with queries containing specific terms from the note and a source filter matching the fixture label. For example, search for the release label and the phrase rollback threshold. Read the returned passage and confirm the numeric value and condition together. A number without its associated unit or condition is insufficient evidence for a deployment decision.
Then ask about a database migration that the note never mentions. An empty or irrelevant retrieval must remain an unknown, not become a made-up migration plan. The source filter supports partial matching in the inspected search path, so a distinctive label reduces accidental overlap with older fixtures. It should not be treated as a security boundary or an exact-match guarantee.
Record state changes and stop at the right boundary
For a second exercise, index a file-backed test note and change its timeout. The store’s search path checks file-backed sources for changes, using modification time as a gate before hashing. Verify the returned source and value after an edit; do not assume that an inline content string tracks a file or that a changed remote website refreshes automatically in the same way.
These are proposed tool exercises, not a report of a full upstream runtime run. Save host version, package version, source label, expected answer and actual passage. If a call fails, distinguish missing tool registration, indexing failure and retrieval mismatch. Do not invoke an upgrade or destructive purge merely to make a first-run demonstration appear successful.
Implementation steps
- 1
Index the sample with ctx_index in a test integration.
- 2
Query release, timeout and rollback facts with ctx_search.
- 3
Ask one unsupported question and record the missing evidence.
- 4
Test a separate file-backed edit without assuming inline content refreshes.
Copy-ready example
{
"tool": "ctx_index",
"arguments": {
"source": "fixture-release-larch-20260907",
"content": "# Release LARCH-42\nTimeout: 18 seconds.\nRollback when the error rate exceeds 2 percent.\nThis note contains no database migration decision."
}
}Frequently asked questions
Why use a source label?
It narrows the intended evidence and makes a result easier to audit. The inspected partial-match behavior is not an access-control mechanism.
Can I index the same note repeatedly to test deduplication?
Do not assume that behavior: the inspected ctx_index annotation explicitly marks the operation as non-idempotent.
Sources
- README.mdSource checked 2026-09-07
- package.jsonSource checked 2026-09-07
- LICENSESource checked 2026-09-07
- src/store.tsSource checked 2026-09-07
- src/search/unified.tsSource checked 2026-09-07
- src/server.tsSource checked 2026-09-07
- src/executor.tsSource checked 2026-09-07
- src/security.tsSource checked 2026-09-07
- src/session/purge.tsSource checked 2026-09-07
- tests/store-bytecap.test.tsSource checked 2026-09-07