Context management
Read the right thing first.
The context advisor answers one question — what should be read for this task — and answers it with locators: a file and its line range, a session id, a cited repository path. Every turn starts with that answer, and every source says whether it could answer at all.
What arrives without being asked for#
Jeden already loads what is always true: the discovered context files (JEDEN.md, AGENTS.md, CLAUDE.md, RULES.md, ~/.jeden/instructions.md, ~/.jeden/context.md, and the instructions a project already keeps for other agents: GEMINI.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md, .clinerules, CONVENTIONS.md, and every rule under .cursor/rules, .windsurf/rules, .clinerules/ and .continue/rules whose front matter says it always applies) and the memories recorded for the working directory. Neither answers what is relevant to the request that just arrived.
The advisor answers that second question in the turn prologue. Before the first model call, the task text is matched against the configured sources and the result is appended to the turn as a [Context recommendations] block: one line per recommendation with its source, its exact locator, its heading and a snippet, followed by every source that answered nothing and why. The block is recorded in the session's own user event, so what the model received is auditable afterwards.
The block is bounded by context.advisor.maxChars and carries the sentence ranked matches, not verified answers: a recommendation is a place to look, never a fact. Set context.advisor.enabled to false to stop injecting it; jeden context prompt "<task>" prints exactly what a turn would receive, and says so when the advisor is off.
An OMP session gets the same answer while it works, through Jeden's proactive-context extension, packages/omp-proactive-context, which OMP loads from its extensions setting. Every OMP tool call states its intent (i, such as Building and installing a new Skarbiec release); the first time an intent appears in a prompt, the extension runs jeden context recommend "<intent>" --json in the session's directory, with the sources and context.advisor.limit Jeden's configuration declares, and does not hold the call back. When the answer arrives, every place not shown earlier in the session reaches the agent unasked, with its locator, heading and matched lines: at its next step while it works, or with its next turn once it has stopped. A declared context.advisor.maxChars bounds that message as it bounds a Jeden turn's block: it carries as many whole places as fit and counts the rest, which a later intent that finds them sends. A refusal (an undeclared context.advisor.limit, a jeden that cannot start, an answer that is not JSON) reaches it once per cause, so silence never means that nothing is known. A session a program reads — OMP's print and json modes (a harsh reviewer, a judge) and a subagent — gets no such messages, since they are not its input. The real journey is JEDEN_TEST_CONTEXT_LIMIT=<n> node tests/context/omp/proactive_omp.mjs: it hands the extension's handlers real intents against the real jeden and the configured roots, measures a budget from the first answer it gets, and keeps what was sent in .build/proactive-context/<run>/report.json.
jeden context prompt "how is a release manifest signed"
jeden config set context.advisor.enabled false
jeden context prompt "how is a release manifest signed"The four sources, and who owns each#
files reads everything readable under the declared roots — documentation, source code, configuration, manifests — and ranks it in chunks. Markdown is cut at its headings and titled by them, because that is where its meaning starts; Markdown before its first heading is titled by the file name. Every other file is cut where a top-level opener starts — a line at column zero after a blank line — and keeps the file name as its title. The opener remains section content: it is searched and appears in the snippet when it carries a query word, but an unparsed source or data line is not promoted to title metadata and given title weight in ranking. A walked entry with no file name is reported unreadable with its path. The locator is path:first-last, so the answer can be read directly, and the snippet is every line of the chunk that carries a query word, whole. Roots are declared in context.advisor.roots as colon-separated path or path@depth entries and default to the project plus ~/.jeden; a root without a declared depth is walked whole. A file with a zero byte in it is not text and is skipped, and .gitignore is respected; no file is skipped for its size and no walk stops at a file or chunk count.
On macOS a walk rooted at the home folder reads only the home's own files and enters none of the folders directly under it. Those folders hold the user's own things — photos, music, the desktop, downloads, other apps' data — and macOS guards them with a privacy prompt in the name of whichever process started Jeden (Oko, when Oko's broker resumed the session), so a session whose working directory is the home asked for Apple Music, Photos, Desktop and Downloads at every turn. A folder under the home is walked when it is itself a declared root, as ~/agents@1 is in the example below. The search tools (grep, glob) apply the same rule to a search rooted at the home.
memory recalls what earlier sessions wrote down for this working directory. The store and its ranking belong to Jeden's memory subsystem — the database JEDEN_DATABASE_URL names, or Jeden's own ~/.jeden/state.sqlite3 when none is configured, scope repo:<cwd> — and the locator is memory:<id>. An empty store is reported as an empty store, not as a missing match.
transcripts asks Transcript Lake, which owns the masked canonical archive of every recorded agent session. The advisor runs that product's own search command rather than reading its files, so the masking stays applied; the locator is session:<id>, which jeden show and the recall_conversation tool read. An event the archive keeps without a session has no locator; it is not recommended, and the source's detail counts how many such events the search matched. An event without a time is titled at no recorded time, and one without text says it carries none, rather than borrowing an empty body. A status reply whose partitions do not each state their part count makes the probe unavailable with that cause.
The same source adds the operator's own messages nearest in meaning to the request, from Oko's meaning index: it runs oko requirements find <query> --top <n> --speaker operator --json as the program Stado's work-registers alternative names, and each message is recommended as the operator's message #<index> of session <id>, located as session:<id>#<index>, scored by its meaning score. Transcript Lake's hits stand when that alternative is unreachable or refuses; the source's detail then ends the operator's words were not read: <cause>, the cause one of jeden.alternatives or jeden.context.transcripts (runtime-unavailable, lake-unrun, lake-refused, answer-not-json, answer-unexpected) naming the oko command.
ground-truth asks the Wisent ground-truth index, which owns cited answers across the organization's repositories. The locator is the citation it returns — repo/path@commit:first-last. The endpoint comes from context.advisor.groundTruthUrl, or from WISENT_GROUND_TRUTH_API or GROUND_TRUTH_API when that is empty; jeden context sources reports which of the three it used.
Every source reports its own answer#
context.advisor.sources defaults to files,memory. Files are local; memory opens the database JEDEN_DATABASE_URL names, or Jeden's own SQLite file ~/.jeden/state.sqlite3 when none is configured, without asking Stado or Skarbiec. Sources run concurrently and their results retain their own availability. --source all also consults the archive and the ground-truth index.
A database that cannot be configured, connected, migrated or queried makes only memory unavailable, with the operation and its cause; completed file, transcript and ground-truth recommendations remain. The memory source runs under its caller's cancellation, which reaches the database operation; it does not consult Stado's resolver, and no setting or flag cuts a source short.
Each selected source emits its own czekam start and completion or failure line, naming the source and workspace, in addition to dependency-level waits. A source thread that panics keeps its source name and panic cause in the unavailable result instead of becoming an unknown source. Standard output remains recommendation JSON, including each source's observed state.
An unknown source name is refused rather than dropped: unknown source(s): nonsense. Known sources: files, ground-truth, memory, transcripts. A narrowed answer is never the result of a typo.
jeden context recommend "why did the release agent quarantine that host" --limit 8 --source all
jeden context recommend "why did the release agent quarantine that host" --limit 8 --source files,memoryReading a short list#
Every answer carries a state for every source it consulted: available or unavailable, the observed reason, how much was considered, how much was returned, and how long it took. A list that is short because a source refused therefore looks different from a list that is short because nothing matched. A count nobody took is null, never zero: every jeden context sources probe and every source that could not answer reports returned as null, printed as asked for no recommendation; a source that could not answer, and the ground-truth health route, which counts nothing, report considered as null, printed as read nothing countable. Desktop's Context screen shows the same words. A files source that read some files but not others keeps both counts it took.
When recommendations are empty and any source was unavailable, the terminal and prompt report that sources could not answer; they do not claim that no matching material exists. Only a completed search across available sources can establish an empty match list.
JSON recommendations expose unanswered: the full source diagnostics for each consulted source that could not provide a valid answer. Successful searches with no matching material are not in this list. CLI, RPC and the agent tool serialize this from the same source outcomes; it is not a fabricated empty fallback. This is a final-result field, not a claim that a still-running dependency has already stopped.
The files source reads every root it is given to the end, so its count of files and chunks is the whole corpus under the declared roots and depths.
A declared root that cannot be inspected retains its path and filesystem cause rather than being labelled missing. Any collected traversal or file-read failure makes the files source unavailable, even when other files supplied readable chunks. Those readable recommendations and their counts remain in the answer; they do not turn a partial scan into success. If no readable sections remain, the detail still lists the collected failures instead of a generic empty-corpus sentence. Recommendations and the sources probe use the same availability and cause, including the RPC consumed by Desktop, and the source wait ends as failed.
An empty memory recall is already a completed answer: recommendations do not launch an additional whole-store health query merely to describe that empty result. The explicit sources probe still reads health; a reachable store with no active records is available, while a missing or invalid health count is reported as an invalid reply rather than silently treated as zero.
A ground-truth search reply must contain its results array. A successful HTTP status with a missing or wrongly typed results field is an unavailable source with the endpoint and schema failure, not a successful empty search.
Each returned ground-truth recommendation also requires the index's nonempty repo, path and commitSha, positive ordered lineStart/lineEnd, string content and numeric score. A malformed selected result makes this source unavailable, naming its URL, HTTP status, result index and decoding or range error. No partial recommendations from that source or invented unknown citation are returned. Titles name the path and append the index's optional heading; a branch name does not replace a missing commit.
jeden context sources asks the same question with no query: which roots exist and how many chunks they hold, how many active memories the store carries, which runtime partitions the archive holds, and whether the ground-truth endpoint answers its health route. A configured endpoint nobody serves reports the URL it could not reach, not silence.
jeden context sources
jeden context sources --jsonHow a recommendation is ranked#
The files source weighs each query word by how rare it is in the corpus it just read, so a word that occurs in nearly every chunk contributes nearly nothing and no list of words to ignore exists anywhere in the product. A hit in a heading, a declaration or a path outweighs a hit in a body; covering more of the query outweighs repeating one word; a long chunk is damped so length alone cannot win.
A word also matches its own stem, so routingu finds routing and signing finds signed, at half the weight of an exact hit. Matching is lexical: a question asked in one language does not reach a document written in another unless they share words, and product names usually are those shared words.
The other three sources rank with their own engines — the memory store's index, Transcript Lake's query, the ground-truth index's score — because each owns its own corpus. Scores are therefore comparable inside a source and not across sources, so the answer interleaves them in a fixed order instead of sorting one list by number.
Every surface#
CLI: jeden context recommend, prompt, sources. A bare first word is the task, so jeden context "why does signing fail" works.
Interactive: /context <task> renders the same recommendations; bare /context keeps reporting the live window size.
Agent tool: context_recommend takes query, and optionally limit, sources. It is a read-tier tool, because it does what the prologue already does unapproved.
RPC and Jeden Desktop: context/recommend and context/sources answer the same objects the CLI prints with --json. Desktop's Context screen is that RPC, not a parsed command line: the sources it offers to choose are the ones context/sources answered, in that order, never a list kept in the app, so a source the advisor gains is offered and one it drops is not sent. A request's parameters are read as stated, never replaced: a query that is absent or blank is refused with context/recommend requires a query, one that is not a string with context/recommend query must be a string; got <value>, a limit that is not a whole number with context/recommend limit must be a whole number; got <value>, and a cwd that is not a string with context cwd must be a path string; got <value>, each as invalid_params. A request with no cwd reads the server's own working directory, and when that cannot be read it is refused as internal_error naming the cause instead of searching an empty path.
RPC context requests are registered before their tracked worker starts, so the inbox remains responsive and an immediate cancellation cannot race registration. context/cancel takes {requestId} on the same connection and acknowledges cancellationRequested: true, not completed termination. An unknown or finished id is refused as request_not_running; a duplicate active context id is refused as request_already_running. Shutdown announces cancellation to every owned context request before joining workers. The memory source's database operation observes the same cancellation; other sources keep their own results.
A terminal context response is emitted only after its active request lease is released. Once that response arrives, the same connection can reuse its id; a completed request cannot be cancelled and reports request_not_running instead of acknowledging a cancellation that did nothing.
Agent-tool, interactive and automatic turn-prologue requests carry their caller's cancellation flag. Stopping a turn therefore also cancels its context preparation rather than leaving that preparation with an unrelated token. A source cancelled before execution answers unavailable with that cause; file traversal and ranking also check cancellation between entries and sections. A kernel file read already in progress still has to return.
The shared database client does not hold its cache mutex while connecting or migrating. Concurrent memory callers wait for initialization through an event-driven condition variable; caller cancellation leaves that wait and cancels the database operation, and failed or panicking initialization wakes the others.
Transcript searches and probes own their child process group until completion or cancellation, including child reaping and pipe drainage. Ground-truth search and health requests observe the same cancellation through both the HTTP request and response-body read. HTTP refusals retain status and body, malformed answers retain the decoding cause and received text, and transport failures retain their nested causes in the named unavailable source. These terminal source results, not the cancellation acknowledgement, establish completion.
The files probe uses the same caller cancellation as a recommendation. A scan stopped between entries is reported as unavailable with the cancellation cause, not as a successful partial corpus or as an empty directory.
Source inspection emits a separate wait for each probe, naming its source and workspace before reading it. Each wait ends with the probe's actual availability or failure detail; a cancelled probe reports cancellation even when no dependency request was started. This gives the same source-level visibility to jeden context sources and the native Context screen as to recommendations.
Real dependency journey#
tests/context/omp/dependencies.mjs runs two concurrent context recommend --source all calls against the real fleet memory database and Transcript Lake, from a new workspace containing one searchable file. It checks that both calls return that file, that the new repository scope exposes no memory from another workspace, and that an unknown source is refused without returning narrowed advice. An unavailable memory database or archive fails the journey; neither is simulated.
Run node tests/context/independent.mjs with JEDEN_BIN, JEDEN_TEST_SOURCE_REVISION and JEDEN_TEST_CONTEXT_LIMIT from the clean candidate checkout. The journey gives the binary a new home and no configured database, and requires context recommend --source files,memory,transcripts to return its file fixture with files, memory and transcripts available, the stand-in ~/.jeden/state.sqlite3 created and named on standard error, and context sources to report files and memory available. It retains every command's status, both output streams and the source statuses in its report; it simulates nothing.
The dependency journey also removes read permission from its own source fixture, verifies the operating system actually denies that read, and requires the files source to retain the path and observed filesystem error as unavailable and unanswered. A privileged process that can still read the fixture fails this case instead of claiming refusal coverage. It then adds a readable companion and requires both recommendations and the sources probe to keep the failed-file cause and failed wait status while preserving the companion recommendation. Permissions are restored and the companion removed after the case; the next real recommendation must recover the original content without changing its bytes.
tests/context/cancellation.mjs exercises cancellation through the real jeden rpc. It points the workspace's context.advisor.groundTruthUrl at a loopback listener that accepts and never answers, sends context/recommend with sources: "ground-truth" and the declared limit, then cancels that request once the connection is accepted. An answer or refusal before the connection fails the journey instead of leaving it waiting for a connection that will never arrive. The answer must list ground-truth as unavailable and unanswered with cancelled by its caller and the URL as its cause; standard error must name both the GET and source waits. A second cancel of the finished id must be refused. The same RPC connection must then return the exact locator and contents of a newly written file through a files-only recommendation, without probing the deliberately unanswered endpoint again. Declare JEDEN_BIN, JEDEN_TEST_SOURCE_REVISION and JEDEN_TEST_CONTEXT_LIMIT and run node tests/context/cancellation.mjs; the report, RPC frames and server standard error are retained under .build/context-cancellation. This controlled network failure qualifies cancellation and recovery, not a live ground-truth index or native rendering.
The cancellation journey rejects a dirty checkout or a binary whose embedded source revision differs from the declared candidate. Its report retains the version command's observed output and status alongside the binary digest. A finished request must return the named request_not_running refusal; transport failure cannot satisfy that case. RPC shutdown must exit successfully without a signal. A protocol or exit failure during shutdown makes the journey fail, but still closes its owned network listener and persists both the original failure and shutdown diagnostic.
Listener startup, workspace configuration and RPC acquisition use the same cleanup scope as the request. A setup failure retains its report and closes any acquired listener; shutdown is attempted only when the RPC transport was acquired. Cleanup releases the held source sockets before awaiting RPC shutdown, so an assertion failure before cancellation cannot leave shutdown waiting on the journey's own source.
node tests/context/omp/citations.mjs qualifies the actual ground-truth index separately. Alongside JEDEN_BIN, JEDEN_TEST_SOURCE_REVISION and JEDEN_TEST_CONTEXT_LIMIT, declare JEDEN_TEST_GROUND_TRUTH_URL and JEDEN_TEST_GROUND_TRUTH_QUERY selecting real cited content. The journey compares native locators with that index's own search response, checks that a genuinely refused route on the same server retains its observed HTTP status and URL without recommendations, then restores the endpoint and checks citations again. Use a stable index during the run; changed search results fail comparison rather than being accepted as equivalent. The clean candidate revision, binary/test digests, commands, HTTP observations and verdict remain under .build/context-citations. No index rows are changed. This journey does not exercise malformed index data, cancellation or graphical rendering.
Configuration#
Every key below is in jeden config list and can be set per user in ~/.jeden/config.yml or per project in <cwd>/.jeden/config.json.
context.advisor.enabled (default true) appends the block to every task prompt once context.advisor.limit is declared: that limit is how many recommendations one answer carries, and while it is unset a task prompt gets no recommendations (standard error says so) and a recommendation that states no --limit is refused naming the key. context.advisor.maxChars, when declared, is the injected block's character budget; unset, the block is whole. There is no advisor deadline setting, and no source is cut short by one.
context.advisor.sources (default files,memory) selects the sources every run consults. context.advisor.roots (default empty, meaning the project and ~/.jeden) declares the roots the files source walks. context.advisor.fileExtensions (default empty, meaning every readable text file) narrows it to named extensions. context.advisor.groundTruthUrl points the ground-truth source somewhere other than its default. The transcripts source runs the transcripts alternative stado capabilities resolve transcripts --consumer jeden names (see Other products); with none on this host the source is unavailable and says why.
jeden config set context.advisor.roots ".@6:~@1:~/agents@1"
jeden config set context.advisor.fileExtensions "md,rs,ts,swift"
jeden context sourcesCompaction, tool-result pruning and the status line#
A conversation compacts on its own only at a token count the operator states. JEDEN_COMPACTION_THRESHOLD names that count directly; otherwise JEDEN_CONTEXT_LIMIT less JEDEN_COMPACTION_RESERVE does. With neither, compaction is /compact alone. A context limit stated without its reserve is refused by name (JEDEN_CONTEXT_LIMIT is <n> but JEDEN_COMPACTION_RESERVE is not set), and so is a reserve that leaves nothing of the limit: Jeden does not pick a share of the window for you. The interactive session refuses to start, and /context refuses to answer, while JEDEN_CONTEXT_LIMIT holds anything but a whole number above zero, naming the value it holds.
Before compacting, Jeden can replace old tool results with a one-line marker. That step runs only when all three of its bounds are stated: JEDEN_TOOL_PRUNE_PROTECT_TOKENS (the newest tool results kept whole), JEDEN_TOOL_PRUNE_MIN_SAVINGS_TOKENS (the least a prune must free) and JEDEN_TOOL_PRUNE_MIN_TOOL_TOKENS (the smallest result worth replacing). With none stated the step is skipped; with only some, the turn is refused with the names of the missing ones.
The status line's route segment is the service tier a model call would carry, chosen in the same order (JEDEN_SERVICE_TIER, then MODEL_SERVICE_TIER, then the fast mode tier); with none stated it shows no route. Its branch and dirty mark come from one git status --porcelain --branch, run when the working directory or the conversation changes rather than on every keypress, so a change made outside Jeden shows after the next turn. A git that cannot run, or fails inside a work tree, puts its cause where the branch would be.
A chat kept by chatMemory never compacts; its view, tree and log are described on jeden chat-memory. Besides the kinds listed there, a work line holds the report of a task given to delegate_task ([<agent> <job id>] and the subagent's final output, clipped like a tool's); a delegation that failed before a subagent ran stays the tool's echo, and a delegated task keeps its own chat in its session directory. Named chats live beside the session root in chats/<name>/ (~/.jeden/chats/ by default). Between turns a background thread builds the line of every message the view does not cover yet and the parent of every sibling pair in the view. jeden import refuses a transcript it cannot read, or whose message lacks a role or carries content that is neither text nor a list of parts, naming the file, the record's byte offset and what is missing.