This guide shows you how to use register_edit() to tell Pyckle which files you're actively working in — so search results surface the right context, not stale ones.
- Pyckle installed and indexed
- Familiarity with basic semantic search (see Your First Semantic Search)
Step 1: Understand How Edit Registration Affects Routing
Pyckle's search results are ranked by semantic similarity — but similarity alone doesn't know where your work is focused right now. register_edit() injects a recency signal into the routing layer, boosting recently edited files in hybrid search results. Think of it as telling the router: this file is hot, weight it accordingly. Without this signal, a deep search might surface older, tangentially related files over the one you just touched.
Routing weights decay over a session. A file registered early in your session carries less weight than one registered five minutes ago. The signal is intentionally time-sensitive.
Step 2: Register a File Edit After Saving
Call register_edit() immediately after saving a file. Pass the full absolute path — relative paths won't resolve correctly against the index. One call per file is enough; you don't need to call it on every keystroke.
register_edit("/home/kp112081/pyckle/code-mcp/src/router.py")Do this every time you make a meaningful change to a file mid-session. The router updates the weight in-memory — no re-indexing required.
Hook this into your editor's on-save event so registration happens automatically. In VS Code, a task that shells out to your MCP client on file save handles this cleanly.
Step 3: Verify the File Is Prioritized in Results
Run a search query related to the file you just registered. The registered file should appear in the top results even if its raw semantic score wouldn't normally put it there. If it doesn't show up, check that the path you passed matches exactly what's in the index — including symlink resolution.
search_code("routing weight decay session")Compare the result ranking before and after registration on a fresh session to see the delta clearly. The boost is most visible when the file's content overlaps only partially with the query.
If you register a file that hasn't been indexed yet, the call silently no-ops. Run index_stats() to confirm your file is in the index before expecting any routing effect.
Step 4: Register Edits in Bulk After a Refactor
After a refactor that touches a dozen files, register them all at once. There's no batch API, but a short loop handles it. Pass every file you meaningfully changed — not generated files, not lockfiles.
files = [
"/home/kp112081/pyckle/code-mcp/src/router.py",
"/home/kp112081/pyckle/code-mcp/src/hybrid_search.py",
"/home/kp112081/pyckle/code-mcp/src/embeddings.py",
"/home/kp112081/pyckle/code-mcp/tests/test_router.py",
]
for f in files:
register_edit(f)Run this immediately after finishing the refactor, before your next search query. The router will weight all four files, and subsequent searches will cluster results around your refactored surface area.
Pull the file list straight from git: git diff --name-only HEAD gives you exactly the changed files. Pipe that into your registration loop to avoid manually listing them.
Step 5: Check Routing Weights via session_summary()
session_summary() shows the current session state — including which files are hottest. Use it to confirm your registrations landed and to see how the router views your active surface area. The "hottest files" list is what the router is actually weighting.
session_summary()The output includes files read, files edited, queries run, and the current hot file ranking. If a file you registered isn't appearing in the hot list, either the path was wrong or the session context hasn't accumulated enough signal yet. Run one more register_edit() call with the corrected path and re-check.
session_summary() is also useful before context hand-off. If you're switching tasks or starting a new session, read the summary first — it tells you exactly where you left off without re-reading every file.