This article records how Noodle Agent gradually grew from a note-generation workflow into a personal knowledge application. I wanted to follow the path from material entering the system to becoming knowledge, supporting questions, and being updated, so that I could understand the implementation behind these features and revisit the choices later.
If you are also trying to connect learning material, knowledge management, and agents, I hope you will read along. This account includes both the approaches currently in use and areas that still need validation.
1 Background and Goals: From a Note-Generation Workflow to a Knowledge Application
The initial need: turning learning material into readable notes
In my day-to-day learning, I initially wanted only to turn PDF slides into notes suited to my own reading and revision, while preserving necessary formulas, images, and source locations. I could then start with the organized content when revising and return to the slides whenever something needed checking.
As the slides accumulated, I found that organizing each document separately was not enough. Different PDFs often covered the same knowledge with different emphases: one focused on one part, another added something else, and neither necessarily covered the whole subject. Reviewing a topic still meant moving between notes and slides to assemble a complete understanding.
I therefore wanted to bring together material about the same topic across sources: retain source support for repeated content, let different emphases complement one another, and create a shared entry point that could be read continuously. The project gradually expanded from a note-generation workflow into a personal knowledge management agent. Asking further questions, checking evidence, revising content, and maintaining sources then became the next problems to solve.
Users can now import PDFs in the workbench, read topic notes and knowledge assembled across sources, switch to the original PDF, ask the assistant questions, inspect tasks, or modify a specified section after approval.

The workbench provides entry points to knowledge systems and notes. Different systems can reference the same knowledge object, so users do not need a duplicate body of text for every classification.
Feature evolution: gradually expanding a generation workflow into a knowledge application
The early generation process used LangGraph to connect parsing, planning, and writing. As the number of notes grew, organizing, using, and maintaining them after generation became work of its own. The project expanded from one-time document processing into ongoing knowledge management.
| Stage | New question | Added capabilities |
|---|---|---|
| Note-generation workflow | How can one PDF become coherent notes? | Parsing, topic planning, local writing, and checks |
| Knowledge accumulation across sources | What supports, complements, or differs about the same object? | Atomic, Concept, sources, and contribution relationships |
| Reading and question-answering workbench | How can evidence be found and checked against the original? | Knowledge navigation, hybrid retrieval, fixed citations, and a reading interface |
| Agents and ongoing maintenance | How can capabilities be used through conversation while long tasks continue? | DSH tool integration, approval interactions, persistent tasks, and recovery |
This evolution gradually produced the current division of responsibilities: notes, sources, and revision rules remain in domain services. DeepSeek Harness (DSH) was later added on the conversation side to reuse capabilities such as sessions, models, and tool loops.
I developed the project independently with Codex. Parsing, model inference, PDF display, and the general conversation runtime reuse existing components, while knowledge objects, business constraints, and the interface were gradually organized around actual usage needs.
Overall structure: how the workbench and backend capabilities work together
Before examining the implementation, three objects need to be distinguished. A Source represents imported material. An Atomic is a topic note that preserves the context of a single source. A Concept provides a shared entry point for the same knowledge object across sources. Users can read these directly, while question answering can organize evidence from currently valid content.

The diagram distinguishes business reads, assistant sessions, and background tasks. Arrows show the direction in which a connection or call is initiated; responses and real-time events are not all drawn individually.
The workbench accesses FastAPI’s source, note, and task interfaces directly over HTTP. Assistant sessions connect to DSH through a Python transport bridge. DSH selects domain tools, and the TypeScript plugin calls Python domain APIs through an HTTP Provider. The session bridge adapts protocols and events; DSH still drives the outer Agent Loop.
Long tasks such as generation, Concept maintenance, and indexing go to independent workers. The API and workers share knowledge storage: SQLite holds identities, revisions, relationships, and task state, while local files hold originals, body text, images, and computed artifacts. DSH stores conversation history separately. The backend enforces domain rules, and the reading interface, assistant tools, and background tasks use the same knowledge constraints.
The frontend uses native JavaScript ES modules and DOM/CSS, with PDF.js, Markdown, formula rendering, and G6 relationship views for reading and interaction. Local-first means that originals, knowledge, and persistent state are stored locally. Parsing, text and vision inference, and embeddings still use configured services; the system is not fully offline.
The knowledge workflow: from source revisions to traceable knowledge objects
When a PDF enters the system, its source identity and specific revision are registered first. Parsed content is organized into a topic plan, then used to generate Atomic notes that preserve the context of that source. When several sources discuss the same object, contribution relationships maintain a Concept. Reading entry points reference these stable objects, and question answering retrieves evidence from chunks compiled from fixed text revisions.

The diagram distinguishes containment, support, contribution, compilation, and navigation relationships. They connect objects with different responsibilities; they do not imply that every node is generated in arrow order.
| Object | Role in organizing knowledge |
|---|---|
| Source / SourceRevision | Store a stable source identity and one specific revision of the original, distinguishing “which source” from “which content revision” |
| Atomic / Concept | Atomic preserves a topic’s context within one source; Concept brings together contributions about the same knowledge object across sources |
| NoteRevision | Fixes the body text of an Atomic or Concept at one revision; edits create a new revision while old citations remain traceable |
| Section | Organizes sections within body text as units for reading, editing, and source associations |
| EvidenceAnchor | Connects body text to a source revision, original page, or parsed material, preserving a basis for verification |
| Chunk | A retrieval range compiled from a fixed text revision and section, bound to a location and hash for retrieval and context budgeting |
| MOC and relationship navigation | Reference stable knowledge objects to provide directories, knowledge maps, and relationship browsing without duplicating text for classification |
These levels of granularity serve reading, maintenance, and retrieval respectively. An Atomic can contain several sections and compile into several Chunks. After a Concept accepts valid Atomic contributions, it retains source relationships; MOCs then organize this text into different reading paths. Answer citations are fixed to the revisions and ranges actually used, so readers can inspect the organized wording and continue back to the original material.
Knowledge production also adds time, model calls, and source-maintenance costs, and rewriting can omit conditions. My goal is repeated reading and ongoing additions, which is why I retained this layer of organized knowledge. For a one-off PDF lookup, directly retrieving the original remains a lighter option.
2 Generating Topic Notes: Organizing a Single Source into Atomic Notes
Topic planning: establishing reading boundaries and source ranges first
A complete derivation in slides often spans several pages: a definition, its conditions, then formulas and examples. Page-by-page generation breaks these connections, while sending an entire PDF to a writing model increases context costs and the cost of redoing failures. Atomic notes therefore follow complete learning topics within one source, allowing readers to follow the necessary content continuously and check the original.
An Atomic can span pages. Sections within it carry reading and editing units such as definitions and derivations, while execution batches limit the scope processed at once. There is no fixed one-to-one mapping among the three. An Atomic also differs from a later retrieval Chunk: the Atomic must first suit human reading, while retrieval passages must serve candidate retrieval and context budgets. Whether to split a topic depends on whether it answers a separate question and whether its complete sources fit the evidence budget.
For SVM, for example, the definition of the geometric margin, the normalization conditions, and the immediately following derivation can form one continuous topic. “Derivation” and “worked example” usually stay inside the note. An oversized topic is split along complete source units while retaining parent and continuation relationships. If a single source block exceeds the budget, it needs structural splitting first; truncating the body text is not a solution.
Parsed results first become source units with page numbers, types, and content. Compact structural information such as headings, continuation clues, and asset availability is then extracted. The planning model uses this to determine topic boundaries, and the program compiles the result into a writing plan that references real source units.

Source units provide boundaries, topic plans define reading ranges, and the program checks coverage, order, and budgets.
Different materials use different organizational cues. Books with trustworthy tables of contents follow chapter ranges; slides emphasize continuous learning topics; papers preserve arguments, methods, and experimental conditions. Unreliable structure can fall back to bounded topic planning. The program checks source IDs, boundaries, and budgets, requiring primary source units either to enter the writing range or to have a justified exclusion record. Supporting material and necessary context can still be reused. A cover can be excluded, but an introduction containing definitions and conditions cannot be discarded solely because of its title. These checks detect missing and duplicate assignments; they do not establish that the model understood everything.
Local writing: producing publishable notes through bounded checks
The writing stage prepares only the current topic’s local sources, necessary context, and asset information. Text is used directly when sufficient, with necessary visual material added for image-bearing tasks. Page screenshots used to help model understanding are handled separately from images in the published note. The latter need real, usable resources, sources, and valid reference paths; a model having seen an image is not enough to include it in the note.

A fixed plan defines the writing range, and local evidence supports drafting and review. Targeted repair is used when needed, followed by independent programmatic validation before publication.
The structured draft in the diagram contains a title, summary, Section text, source assignments, and omission reasons. The program uses these to compile text, validate ranges, and bind assets. New tasks currently receive one section-level semantic review and, when there are actionable corrections, one targeted repair. An unavailable review leaves a warning. Repair suggestions can also be false positives; if repair is unavailable or its result is unsuitable, the original draft can be retained if it passes the required checks. Format recovery also has a call limit, rather than reviewing repeatedly until the model declares satisfaction.
The final pre-publication programmatic validation checks whether structure, sources, assets, and the current revision meet the constraints. Content failing necessary conditions retains diagnostics and recovery records instead of being published as a broken artifact. A published revision means that the current publication contract passed. Completeness of formula conditions and correctness of derivations still need checking against the original. Model review and programmatic validation serve different purposes and cannot replace one another.

The SVM note displays a table of contents, text, and illustrations, with an entry point back to the original PDF.
Execution costs: reducing repeated input and repeated work
Waiting time and repeated work need separate treatment. The following diagram separates work scheduling from stage-result reuse: scheduling determines which work can overlap, while reuse determines which steps can use existing results directly.

Scheduling retains the join point after all drafts in a batch arrive. Reuse determines what must continue based on compatibility of stage inputs, policies, and artifacts.
Scheduling starts with text-first processing and bounded concurrency. Text-only tasks can run first, while tasks containing images continue writing once the necessary visual material is ready. Executable text work can therefore overlap slower visual processing. Drafts within a batch must still all arrive before checks and publication; parallelism does not remove that join point. Batch publication lets readers begin with completed portions, so first readable output, complete generation, index availability, and completed Concept maintenance need to be observed separately.
Stage-result reuse first checks input fingerprints, execution policies, and artifact hashes. Compatible matches reuse saved results and avoid repeating the step. New calls or computations are scheduled only when the stage result is missing, with receipts saved afterward. Incompatible or damaged results cannot simply be treated as ordinary cache misses and recomputed at will; Chapter 6 discusses the recovery constraints.
Token and cost control also starts with the input itself: compact planning reduces structural input, local evidence avoids resending the whole source each time, bounded repair limits extra calls, and model-role routing assigns writing and checking tasks. Concurrency mainly changes waiting time and does not itself reduce tokens. Compact input and trustworthy reuse may reduce the corresponding inputs or calls. The main entry points for topic planning and local generation are source_sections.py::make_plan and assembly_generation.py::SourceSectionPipeline.run.
Planning granularity also affects this cost. Excessively small notes repeatedly introduce background into writing inputs and create more maintenance objects. Oversized notes make changes and error localization difficult. Range planning therefore establishes what each note must cover before writing handles how to express it, reducing the need to redefine reading boundaries while generating content.
3 Knowledge Across Sources: Maintaining Concepts and Building a Knowledge Graph
Objects and contributions: identifying the same knowledge before judging what is new
When a textbook is added after slides, a new Atomic may repeat an existing definition, complete its conditions, or offer different wording. A Concept provides an entry point for the same knowledge object across sources. The first judgment concerns object identity, followed by content contribution. Identical names do not guarantee identical boundaries, and concepts that frequently occur together cannot simply be merged, such as a support vector machine and a type of kernel it uses.
The system combines valid Atomic notes, source-planning context, existing bindings, and Concept candidates to form a bounded identity plan. Candidates provide names, aliases, definition boundaries, and necessary core information, reducing repeated input of the entire knowledge base. Compression can also omit objects, so absence from the candidate set cannot establish nonexistence. Uncertain assignments may remain pending while the original Atomic stays readable and checkable.

Confirm the object first, then distinguish source support, core additions, and content awaiting confirmation.
After identity is confirmed, the next question is how the new material affects the text.
| Contribution | Effect on the text |
|---|---|
| Duplicate support | Adds valid sources; the text may remain unchanged |
| Core addition | Adds necessary content such as definitions or conditions, triggering a core update |
| Further reading | Creates reading links without directly becoming core facts |
| Background information | Retains context without triggering a core update |
| Conflict | Records disagreement for confirmation rather than merging it directly into conclusions |
For example, a textbook repeating the geometric margin definition needs only to add support. Completing the normalization conditions may require a core update. Superficially different formulas may reflect notation conventions, so source type alone cannot determine which is right. Preserving conditions and sources lets readers check the differences.
Contributions also need binding to specific Atomic revisions and passages. This keeps different content from similarly named sources from being mixed solely by title, and allows later checks of which definition, condition, or image contributed to maintenance. Identity assessment establishes object boundaries; contribution assessment determines text changes. Evidence is retained for each step separately.
Shared knowledge: a concise framework with complete source context preserved
A Concept’s default core section appears as “Knowledge Framework” in the interface. Markdown subheadings organize its topics to help readers form a concise understanding. Full derivations, long worked examples, and code remain in Atomic notes, avoiding duplication of every detailed explanation in the shared text whenever a source is added.
Construction uses currently accepted contributions whose dependent Atomic notes remain valid. With identical inputs or additions that only provide evidence, the existing text can be reused subject to conditions such as continued validity of its support. A core addition can update text using the still-supported previous text and new passages. New foundational material or targeted repair may also require reorganization. The current default maintenance unit is the entire core text. Identifying affected topics does not mean arbitrary paragraphs already support precise incremental updates, and author-protected sections cannot be overwritten automatically.
Images also require independent assessment. A new source may add no definition but offer a clearer structural diagram; its source and basis for use still need preserving. Readers should see a shared framework, valid support, and differences awaiting confirmation, with paths back to each Atomic. Chapter 6 examines eligibility and rebuilding constraints after sources change.
Building the knowledge graph: reading navigation through MOCs and object relationships
MOCs (maps of content) provide two entry points. A source MOC preserves the hierarchy of the frozen topic plan and binds published Atomic notes’ stable IDs to directory entries. A cross-source knowledge map starts from currently valid Concepts, groups and orders them by domain, and creates reading entry points. Multiple locations can reference the same object without duplicating its text. Domain grouping does not itself infer semantic relationships between concepts.
The knowledge graph further aggregates these objects and relationships while preserving separate layers: MOC navigation membership, semantic and hierarchical relationships, document links in the text, and source support from Concepts to Atomic notes. Queries filter invalid support and missing targets. Unconfirmed suggestions are not shown as accepted relationships by default. The frontend can display relationship layers or a local neighborhood around an object to reduce the reading burden of the full graph.
These connections mean different things. Directory membership indicates where to begin reading, a text link shows what an author points to, and source support explains which notes shared knowledge depends on. Layered display preserves these distinctions so that “placed in the same directory” is not mistaken for “a confirmed knowledge relationship.”

The relationship view helps locate objects and check sources, with zooming and local browsing.
This graph serves reading, navigation, and source checking. Directory entries cannot directly act as factual evidence for answers, and an edge does not mean answers retrieve along that edge. The current implementation cannot therefore be described as GraphRAG. The main implementations for cross-source maps and graph projection are navigation.py::refresh_maps and graph_projection.py::projection. Question answering still retrieves and organizes evidence from the underlying text revisions.
4 RAG Question Answering: From Online Retrieval to Evidence Assembly and Fixed Citations
Knowledge production yields readable notes; question answering must still find evidence suitable for the current question. Noodle Agent primarily searches published, valid Atomic and Concept text. PDFs preserve original evidence and page numbers, while MOCs and the knowledge tree provide reading entry points. Conversation history can help resolve references, but does not directly become the factual retrieval corpus.
Offline indexing: compiling retrieval passages from fixed text revisions
The index is prepared before a user asks a question. The program reads fixed text revisions, splits within Sections along boundaries such as paragraphs, formulas, and code, then compiles Chunks under token budgets. Atomic notes organize continuous reading around topics, while Chunks serve retrieval and context budgets, so their sizes and boundaries need not match. Each Chunk binds to a note, revision, section, text range, and hash so that results can return to the content as it was.
The same Chunks are compiled into FTS5 lexical entries, embeddings, and a vector index. Vector input includes the note title, section title, and body text. Reuse of cached embeddings depends on conditions such as the embedding configuration (profile) and text hash. The current default uses a normalized matrix and exact NumPy scanning. Introducing approximate retrieval would require measurements at the target scale.

Text is split before lexical and vector artifacts are prepared separately. A complete index becomes the active snapshot only after validation.
While a new index is built, queries continue using the activated snapshot. Publication and index readiness are therefore separate states: notes may already be readable while question answering still reports that the index needs updating. The main entry points for splitting and indexing are compile_chunks and Indexer.build. Chapter 6 explains how stale results are prevented from taking effect at commit time.
Revisions, passages, and vectors in the index must stay aligned. Activation is allowed only after lexical entries, vectors, and the index Manifest are complete, keeping queries from using unfinished artifacts. Snapshots also make it possible to check which revision produced a hit later.
Online retrieval: two-path retrieval and ranking within a defined scope
When a user asks a question, the service first determines the retrieval Scope from application context, then obtains the active index and checks current eligibility. GLOBAL can use all currently eligible Atomic and Concept notes. NOTES limits retrieval to specified notes. SOURCE uses only Atomic notes supported by the selected source, preventing cross-source Concepts from introducing evidence outside that scope. Entity hints such as the current object help interpret the question but cannot expand the scope.
Eligibility checks also consider whether text is the current revision, whether sources have been withdrawn, and whether publication policies and support remain valid. Ineligible content cannot enter candidates even when its old vectors remain in the active index. Lexical and vector retrieval share this candidate allowlist, ensuring that both paths compare within the same scope.

Scope and current eligibility constrain candidates. Results from both paths pass through fusion and optional reranking before evidence assembly and answering.
Hybrid mode runs FTS5/BM25 and vector retrieval in parallel. BM25 complements matching for precise terms and symbols, while vector similarity handles differences in expression. Their score scales differ, so the program uses Reciprocal Rank Fusion (RRF) to merge results by rank rather than adding raw scores. Fusion scores rank candidates; they are not probabilities that an answer is correct.
For a passage , the current equally weighted two-path fusion is calculated as follows:
Here, is one retrieval path’s result list. Ranks start at 1, and each path first deduplicates by Chunk ID. A passage appearing in both lists receives the sum of both contributions; one appearing in only one list receives that path’s contribution alone. The value 60 is a fixed smoothing constant in the implementation. There are no separately adjustable weights for the two paths.
Candidates can then be reranked according to configuration. Automatic mode allows fusion results to be retained when reranking is disabled or fails, with the reason recorded. A mode requiring reranking returns failure when its conditions cannot be met. Reranking can only reorder existing candidates; evidence absent from the retrieval pool will not appear because of it. Ranked hits then pass to context assembly.
Evidence and citations: turning retrieval hits into traceable answers
After a Chunk is retrieved, the program rereads fixed text, checks its location and hash, expands neighboring content within the same section according to rules, and merges overlapping ranges. Both per-note allocation and total context tokens have limits, preventing one highly relevant note from displacing other necessary evidence. The answering model receives the bounded evidence package produced by these steps.
Relevant material is not necessarily sufficient. To explain why the full SVM margin is , for example, context must include the normalization convention, the one-sided distance from a support hyperplane to the classification hyperplane, and the complete two-sided margin. Retrieving a note mentioning “maximum margin” may not provide those conditions. Neighborhood expansion can restore nearby explanations, but budget trimming can remove necessary content again. Retrieval and reranking cannot invent conditions already missing from the upstream notes.
Answers use structured claims and citation_ids to bind statements to citations within the current evidence. The program first restricts citations to valid targets, then checks support for important claims. The current policy allows at most one correction when needed: severe support problems block release, while correctable problems produce a revised draft from the same frozen evidence. That draft receives no second semantic review. Structure, citation validity, and final evidence eligibility still need checking.
Final citations are fixed to a specific revision, section, text range, and hash, retaining information for returning to the PDF. Later note updates leave old answers pointing to the text used at the time rather than silently changing to a new revision. Accurate location and semantic correctness remain separate judgments: a matching hash establishes that the referenced content has not changed, not that it supports the answer’s inference.
Sources can also change between evidence retrieval and answer delivery, so current evidence eligibility is checked again at the output boundary. Old citations can remain for historical inspection without allowing invalid content into current question answering.
Insufficient evidence produces the corresponding business status, such as an index awaiting update, a coverage gap, or content changing during execution. Configuration mismatches and provider errors instead require checking configuration or service availability; they should not become “the knowledge base has no answer.” The frontend and agent need to present these results accordingly. A successful HTTP request does not establish answer reliability. The online path can be followed from Searcher.search and Answerer._answer.
5 Agent Applications: Question Answering and Controlled Editing Through Domain Tools
Knowledge-answering and revision interfaces provide capabilities; the agent connects them to conversation. Users describe what they want to understand or change, the runtime organizes calls, and domain services continue validating knowledge objects, evidence, and modification conditions.
Runtime choice: why DeepSeek Harness and Cordis were integrated
The initial note workflow mainly handled a fixed source-to-note process. Adding question answering, close reading, editing, and task management created further interaction needs: conversation history, model and tool loops, approval, cancellation, context compression, and tool-result display. I chose DeepSeek Harness to reuse these general capabilities while continuing to maintain knowledge objects, sources, and publication rules in Python services.
DSH is built on Cordis. Cordis provides shared context, service injection, events, and plugin lifecycle management. Plugins declare dependencies, obtain services through context, enter operation when dependencies are ready, and clean up their registered capabilities when unloaded. DSH’s Agent Loop, model adapters, tool registration, and session storage are themselves provided by plugins assembled through configuration. Further details are available in the DSH architecture guide and Cordis implementation.
By responsibility, the plugin system can be divided into the following parts.
| Part | Main modules or plugins | Capabilities |
|---|---|---|
| Assembly and lifecycle | Cordis Context, Service, plugins, and events | Dependency declarations, service injection, loading, and cleanup |
| Agent execution | dsh-agent, dsh-agent-loop, dsh-llm, dsh-tools | Agent interfaces, default execution loop, model calls, tool registration, and execution |
| Context and sessions | dsh-session, JSONL persistence, dsh-system-prompt, compaction and result-pruning plugins | History persistence, request assembly, and context-length control |
| Policies and runtime support | Approval, permissions, sandbox, timeout, task, and usage plugins | Execution constraints and runtime records according to configuration and platform conditions |
| Web application | Webserver, API/RPC, Workspace, session projection, and client UI plugins | Browser host, session transport, workspace, and result display |
| Domain extension | @noodle/agent and its client-side tool cards | Connects knowledge-domain operations to these runtime capabilities |
These are upstream composition responsibilities; the active plugins depend jointly on the profile, platform, and service dependencies. Noodle uses the Web profile, layering shared base packages, Web application packages, and its own plugin patches. The knowledge assistant preset further configures its persona, basic compaction, the /compact command, and tool-result pruning. CLI profiles and patch configuration explain this assembly method.
The project’s root plugin mounts five modules through ctx.plugin(...), with the entry point in src/index.ts.
| Noodle module | Role in the project |
|---|---|
NoodleHttpProvider | Provides ctx.noodle, converting domain tool requests into Python HTTP calls |
ReadTools | Registers question-answering, retrieval, and close-reading tools |
NextTools | Registers discovery, status, and write tools, requesting approval before writes execute |
AgentGuidance | Injects knowledge-assistant rules and the current Scope/object context |
WorkspaceBootstrap | Registers the local working directory and title |
This integration requires maintaining contracts for plugins, events, and result display, as well as following dependency upgrades. The choice reflects the interaction capabilities the project needed to reuse; there are no cross-framework experiments here supporting a general performance ranking.
Runtime and domain services: connecting conversation, tools, and the interface
A request enters the Python session bridge from the workbench’s AgentClient, then passes to a DSH Session. The outer model selects tools, and the TypeScript plugin calls Python domain APIs through the HTTP Provider. The session bridge and knowledge API belong to the same FastAPI application. The former adapts session protocols, the latter enforces knowledge rules, and DSH drives the outer Agent Loop.

DSH organizes outer tool calls, Python performs knowledge question answering, and tools return answers, citations, and conclusion markers to the runtime.
The main workbench still uses native JavaScript. Published answer cards in the DSH host use React and client slots. Session transport, domain execution, and answer display have separate responsibilities; client UI plugins do not hold knowledge-domain state.
The frontend receives text, tool, approval, and execution states through SSE. DSH may continue running after a disconnection. The client fetches authoritative history from the original session and merges and deduplicates events by seq, without resubmitting the original prompt. After switching sessions or destroying a panel, instance-lifetime and request-generation checks constrain late responses so that old responses do not overwrite the new interface. Historical pages still require explicit loading. Restoring the displayed session and persistently executing background tasks are handled separately.
Domain tools: from capability discovery to answering and controlled changes
Noodle currently registers 17 domain tools. This count includes only the project’s own business tools; DSH can provide other general tools according to configuration. The complete domain list follows.
| Category | Tool | Implemented function | Write approval |
|---|---|---|---|
| Answering and close reading | noodle_answer_knowledge | Retrieves, answers, and checks support within the current scope, returning fixed citations; ordinary questions conclude the turn | Not required |
| Answering and close reading | noodle_search_knowledge | Locates relevant notes and evidence passages; it is not a mandatory prerequisite for ordinary questions | Not required |
| Answering and close reading | noodle_get_atomic_note | Reads an Atomic’s compact table of contents or specified sections | Not required |
| Answering and close reading | noodle_list_concepts | Finds current Concepts by title or alias and returns compact information | Not required |
| Answering and close reading | noodle_get_concept | Reads a Concept’s table of contents, specified sections, and supporting notes | Not required |
| Discovery and status | noodle_get_readiness | Inspects retrieval configuration, index preparation, and the presence of model configuration without calling a model | Not required |
| Discovery and status | noodle_list_knowledge | Paginates Atomic, Concept, and MOC identities and titles, with optional filtering by source revision | Not required |
| Discovery and status | noodle_list_sources | Finds sources, filenames, and current source revision IDs | Not required |
| Discovery and status | noodle_list_tasks | Finds generation tasks and brief progress by source or status | Not required |
| Discovery and status | noodle_get_relations | Views hierarchy, links, and source support around an object | Not required |
| Discovery and status | noodle_get_source_status | Separately inspects text publication, index, and Concept-maintenance status | Not required |
| Discovery and status | noodle_get_task | Reads a known task’s persistent timeline and current progress | Not required |
| Discovery and status | noodle_list_knowledge_roots | Lists root navigation entry points for knowledge systems | Not required |
| Approved writes | noodle_edit_section | Publishes section changes against a target and revision baseline, requiring a reread on conflict | Required |
| Approved writes | noodle_refresh_knowledge_map | Refreshes derived navigation from current Concepts without regenerating knowledge text | Required |
| Approved writes | noodle_pause_task | Pauses an explicitly selected existing generation task | Required |
| Approved writes | noodle_resume_task | Resumes an existing task from checkpoints without creating a new whole-source generation task | Required |
Tool use first distinguishes stable identities from display names. Parameters separately represent notes, source revisions, text revisions, and tasks to avoid mixing different IDs. Close reading starts with a compact table of contents and then reads the target Section, reducing whole-note input. Tool descriptions and schemas help the model call correctly; domain interfaces still validate whether parameters are valid in the current state. Definitions can be read in read-tools.ts and next-tools.ts.
Ordinary questions can call noodle_answer_knowledge directly because it already performs retrieval, answering, and support checks internally. After receiving the domain result, the tool sets a conclusion marker with exec.concludeTurn() by default. DSH concludes the turn, and the frontend displays the published answer and fixed citations directly, reducing opportunities to lose evidence through another rewrite by the outer model. continue_task is used only when the user explicitly asks for further action after answering. A non-READY status still ends the turn. One tool call may contain several model requests, so tool counts cannot stand in for costs.
Writing requires another set of conditions. noodle_edit_section first reads the current section and submits new content with expected_revision. The workbench shows the target and parameters, letting the user allow it once or reject it. After approval, the backend still checks the target, asset references, and concurrency baseline. If another operation has changed the same target section to different content, it returns a conflict and requires rereading. Changes to other sections may still be mergeable, and an already-satisfied target can return unchanged.
Approval expresses the intent to execute; concurrency checks determine whether the current change can commit. Read Scope is not yet a complete write-authorization system. Identity, write permissions, and isolation need separate design for multi-user use. Conversation history and compressed content can only help interpret references; new factual questions still need current evidence. Configuration or provider failures must not be disguised as normal answers by continuing to traverse the entire knowledge base during the turn.
6 Optimization, Reliability, and Evaluation: Controlling Execution Costs and Assessing Results
Workflow optimization: reducing waiting time and model costs separately
Once the generation pipeline works, optimization first needs to identify where costs arise. Slow parsing or visual processing calls for a shorter critical path. Repeatedly supplying the same material calls for smaller inputs. Regenerating unchanged content calls for checking whether tasks and artifacts can be reused. More concurrency alone cannot solve all these problems.
The efficiency diagram in Chapter 2 shows execution within one batch of material. Across the system, current optimizations focus on the following areas.
| Area | Approach | Main effect |
|---|---|---|
| Waiting and scheduling | Text-first processing, bounded concurrency, and batch publication, retaining the requirement to gather all drafts in a batch before checking | Lets overlapping stages progress together and provides the first readable batch earlier |
| Model input | Compact structures for topic planning, local evidence for writing, and tools that read tables of contents before sections | Reduces repeated input of complete sources or whole notes |
| Repeated computation | Reuses parsing, visual processing, embeddings, and stage artifacts based on inputs, configuration, and content hashes | Avoids computation or calls for existing results under compatible conditions |
| Knowledge maintenance | Distinguishes duplicate support from core additions and merges maintenance requests with identical inputs | Reduces repeated construction when text has not changed |
| Repair and conversation | Limits review and repair attempts and concludes ordinary turns after domain question answering | Controls repeated work and additional outer-model rewriting |
| Model routing | Selects models by task role and configuration | Changes per-call costs; it does not automatically reduce tokens |
Bounded concurrency mainly affects waiting, while compact inputs and compatible reuse directly affect repeated tokens or calls. Each has conditions: topics must not be compressed until necessary content disappears, maintenance must not skip real additions, and reuse must not mix in results from old inputs. Revision and recovery mechanisms keep these optimizations consistent with the current knowledge state.
Timing needs separate measurements for first readable output, complete generation, index availability, and completed background maintenance. Durations of overlapping stages cannot simply be added. Costs must also include calls inside Python for writing, review, RAG, visual processing, and embeddings rather than only tokens shown in the DSH conversation panel. These mechanisms are implemented, but actual savings and possible quality effects still need controlled comparisons under fixed conditions. Historical percentages from older versions are not treated as current benefits.
Revisions and eligibility: constraining current use after sources change
SQLite stores source and note identities, revisions, current pointers, relationships, and task state. Local files store PDFs, text, images, and computed artifacts, while DSH stores conversation history separately. Identities point to the same object, and revisions fix its content at a particular point. Editing creates a new revision while old citations still return to the original text range. File reads check hashes to ensure that content matches its record.
Historical traceability and current usability are separate. After a source is replaced or withdrawn, reads, indexing, and question answering filter by current eligibility while background work updates Concepts, indexes, and navigation. Eligibility checks include the current revision, publication policies, source status, and valid Atomic support. An old Concept still depending on invalid inputs cannot be made wholly eligible merely because some valid support remains. Its text may still contain content from a withdrawn source and needs the corresponding maintenance.

Text publication, Concept construction, and index activation follow similar sequences: prepare artifacts, check inputs against the current baseline, then advance pointers in short transactions. Expected revisions prevent old edits from overwriting new text. A Concept’s input signature records valid contributions, while its expected generation determines whether a build is stale. Index activation checks that participating revisions remain eligible and that another build has not advanced the active head. Each check constrains its own object; a generated file alone is insufficient.
The file system and SQLite do not share a transaction. Failed metadata commits can leave unreferenced artifacts, and database rollback cannot undo remote calls. Immutable files and short transactions narrow the state transition, but this storage boundary still needs to be accepted and handled.
Persistent tasks: leases, checkpoints, and commit validation for recovery
Independent workers handle parsing, generation, and knowledge maintenance. Task records live in SQLite and do not depend on a page or chat turn staying open. A worker claims a task with a time-limited lease and renews it through heartbeats. Another executor can take over after expiration. Even if the old executor returns later, it must pass commit guards and cannot continue advancing the task or overwrite new results.
Tasks also record attempts, current stage, and results. Work can be deferred while conditions are unmet, and consecutive failures reaching the limit need intervention rather than indefinite retries that hide the problem. Worker liveness and actual task progress therefore need separate observation.

During recovery, checkpoints first compare stage-input hashes, then reread artifacts and validate their integrity. Execution profiles also constrain parser, model, and policy choices to prevent incompatible results from entering the same recovery. Existing results are reused only when inputs and configuration are compatible and artifacts trustworthy. Changed inputs produce a conflict. Final commit still revalidates the lease, valid inputs, and current revisions; checkpoints cannot replace the final concurrency check.
These constraints cannot guarantee that external calls occur only once. A model service may finish a request while the local process crashes before saving the response. Recovery may then repeat the call and incur another charge. Lease expiration also cannot guarantee immediate cancellation of remote requests already sent.
Before submitting to MinerU, the program saves an INTENT. Once it receives and saves the remote batch ID, recovery can continue querying that batch. If only the submission intent remains, whether the remote service accepted the request is unknown. The program stops and requires checking server-side status rather than safely assuming it can resubmit. There is no general end-to-end exactly-once guarantee here.
Engineering checks: what interfaces, state, and recovery mechanisms cover
The project has validation entry points for Python, TypeScript, HTTP contracts, frontend lifecycles, and isolated workflows. They check interfaces and state transitions, approval wiring, concurrency protection, and recovery behavior. A synthetic Provider can work with real DSH/API components to check protocols, but does not establish that a real model always chooses the right tools or writes correct content.
After generation, verify_generation rereads published artifacts and checks current revisions, bindings between candidates and review receipts, source-unit coverage, mathematical formatting, and image resources. It provides engineering and content-format gates without proving symbolic derivations or facts. Production model review is also only one stage of generation. Task success, an index being READY, and a passed review each indicate that the corresponding checks passed; together they do not establish content correctness.
Existing RAG evaluation scripts provide note-level Hit, Recall, MRR, and nDCG, with relevance annotations still incomplete. In the QA branch, behavior_pass checks whether answerable questions return READY and unanswerable questions reach the expected refusal status. Neither is directly an answer’s semantic accuracy, nor do they establish that final context contains all necessary evidence.
Content evaluation: locating quality problems along the evidence chain and comparing changes
The next requirement is an independent gold standard built from originals, with problems traced through “original → parsing → Atomic → Concept → retrieval candidates → final context → answer.” Gold annotations record necessary facts, conditions, original locations, permitted equivalent expressions, and prohibited errors. Questions derived from generated notes may leave omitted content outside evaluation as well.

The diagram shows evaluation methods and future plans. A complete independent content-evaluation platform remains to be built.
Each layer examines different objects. Atomic evaluation checks necessary facts, formula conditions, and correspondence between text and images. Concept evaluation checks mistaken identity merges, missed additions, and conflict handling. RAG evaluation checks whether final context covers necessary evidence groups. Answer evaluation checks conclusions, conditions, and citation support. Agent evaluation also needs to check whether actual state satisfies goals and operational constraints, not just whether the final reply claims completion.
Programs are suited to checking identity, revisions, ranges, and citation locations. Semantic judgment requires humans to return to originals and adjudicate. Model scoring can help, but should first be calibrated against people and retain disputed cases. With small samples, showing success counts, denominators, and failure examples also makes problems easier to understand than a single aggregate score.
Diagnosis first locates where necessary facts disappear, while preserving the possibility of independent downstream errors. If Atomic notes already omit conditions, changing reranking cannot restore them. If context is sufficient but the answer is still wrong, investigate the answering stage. For RAG, also distinguish whether originals are sufficient, current knowledge is sufficient, and material within the specified Scope is sufficient, so that missing knowledge, scope restrictions, and retrieval failure are not confused. Necessary evidence can be grouped by fact, allowing equivalent sources within a group without requiring every duplicate source to be retrieved.
Comparisons need fixed sources, models, prompts and review policies, retrieval scope, budgets, cache state, and concurrency conditions before examining quality, waiting time, and costs. First readable output, complete generation, and background convergence should be recorded separately. Costs per successful task include failed attempts, with missing usage marked unknown. Tuning cases and held-out cases should also be separated by source or topic to reduce leakage between different phrasings of the same fact.
The independent content-quality baseline remains incomplete; existing engineering checks cannot establish those quality conclusions. Unapproved writes, expanded reading scope, old results overwriting new revisions, and invalid sources entering current answers are boundaries requiring separate checks. Higher average scores cannot offset these problems.
7 Current Progress and Next Steps: Usage Boundaries and Development Priorities
Current capabilities: connected workflows and suitable uses
Noodle Agent connects source import, Atomic generation, Concept maintenance, knowledge maps, reading and question answering, and agent editing. Users can return from notes to sources, ask within defined scopes, approve changes, and inspect background task progress. Revisions and contribution relationships support ongoing maintenance as knowledge changes, while task recovery lets long workflows continue independently of a single page request.
The current focus remains a personal, local-first learning tool. Knowledge files, SQLite, workers, and external model services need configuration for the environment. Read Scope and edit approval should not be treated as complete authentication, write authorization, and multi-user isolation. Shared use or larger deployments require separate design for these boundaries rather than carrying over local trust assumptions.
Development order: establish quality evidence before extending for actual needs
The next step is to complete quality evidence for existing workflows, then decide where to invest based on the main problems.
| Order | Focus |
|---|---|
| First priority | Establish an independent quality baseline, with original evidence for tracing important failures |
| Next | Fix the main error-producing layers and confirm that changes solve actual problems |
| Ongoing | Clarify module, resource-ownership, and DSH protocol boundaries to reduce maintenance costs |
| Later extensions | Bring audio, video, and other learning materials into the same knowledge-organization and source-checking workflow |
Input is still primarily PDF, with image and visual processing supporting understanding of that material. I hope to add multimodal sources such as lecture recordings and explanatory videos. Audio transcription would need timestamps; video would need organized subtitles, keyframes, and explanatory segments, with those sources mapped to Atomic and Concept objects. Citation checking would also expand from PDF pages to audio and video time ranges so that readers could return to the locations actually supporting a conclusion. These are future directions, not completed input pipelines.
Architectural expansion is driven by actual scale and evidence of failures. New infrastructure becomes a question when existing storage, retrieval, or execution no longer meets the target scenario. The project continues to focus on turning material into readable, traceable knowledge that can be maintained over time. Implementation details and further progress are available in the Noodle Agent project repository.


