OpenShelf: Let AI Think Within Your Knowledge Boundary

OpenShelf wants the knowledge base to participate directly in AI thinking: an agent should use the user's knowledge range, coding habits, and working style to explore answers the user is more likely to accept, and change direction when it moves outside that boundary.

Abstract

OpenShelf is a local-first MCP server for building searchable DuckDB knowledge bases from PDFs and local documents.

Traditional knowledge bases mostly help a model answer "what is in the material?" OpenShelf is concerned with another question: can a knowledge base change the direction in which AI searches for an answer, so it uses the user's knowledge range, past choices, and soft preferences to find solutions the user is more likely to accept?

A set of high-school math textbooks may not contain the answer to a difficult problem, but it defines the knowledge primitives the student is allowed to use. A hard high-school problem may be solvable with out-of-scope mathematics, but the important skill is performing a long chain of reasoning inside the high-school framework. The history of an AI personal assistant may not contain the exact implementation for the next programming task, but it records which plans the owner accepted or rejected in similar situations. Brute force might work, but good code should optimize time and space under real hardware constraints. As AI becomes more capable, it should provide not only a correct answer, but an answer the user can accept.

Simple prompt engineering may not solve this well. "Use high-school knowledge" is vague, because high schools around the world use different knowledge frameworks. "A single code run must not exceed two hours or 16 GB of memory" asks the user to state a fairly technical rule. In many consumer situations, the useful signal is more contextual: "the user manually stopped code that ran for an hour and asked whether it could be accelerated," or "the user rejected my proposal to provision a 32 GB machine."

OpenShelf is therefore not meant to make AI merely repeat the knowledge base, nor to run a compliance check only after the answer is generated. Retrieved knowledge, methods, and historical precedents should enter the AI's thinking process. They should influence how candidate solutions are generated and ranked. If a direction is out of scope or inconsistent with the user's habits, the AI should switch direction with a concrete reason and keep searching for a more acceptable solution.

This is a mode of work where knowledge primitives are closed, but reasoning combinations remain open.

1. AI must solve not only what is correct, but what will be accepted

No matter how capable AI becomes, real tasks are not unconstrained answer-search problems. Users usually care not only whether the result is correct, but also what knowledge it uses, what method it applies, and whether the solution fits their background and habits.

Consider a difficult high-school math problem.

It may have a short university-level solution: derivatives, Lagrange multipliers, Taylor expansion, or a theorem the student has never learned. The answer can be mathematically correct while still not being the answer the user needs.

The AI may know multiple correct answers. What the user actually needs is:

Can the AI solve the problem using only what this student has actually learned?

Writing "please use high-school knowledge" in the prompt does not fully solve the problem. "High-school knowledge" is not a universal set. A science-track student in China may have learned derivatives while another track has not. In the United States, calculus exposure varies by state, school, and curriculum.

The reliable boundary is therefore not a vague label, but the textbooks, course materials, and learning records the user has actually used.

After these materials enter a personal knowledge base, the knowledge base should affect how the AI thinks from the start. If calculus is outside the current knowledge range, it should not be the preferred candidate method. If completing the square, basic inequalities, and geometric transformations appear repeatedly in the materials, those methods should be ranked higher.

This does not restrict the AI's capability. It gives that capability a direction. The value of the hard problem may be exactly that the allowed knowledge is elementary, but must be combined deeply. The AI should spend its computation and reasoning power inside the solution space the user can accept.

2. How OpenShelf differs from systems that can only search a knowledge base

A normal knowledge base or RAG system often follows a short chain:

question -> retrieve relevant text -> pass text to model -> generate answer

OpenShelf wants to support a different chain:

question -> decide whether the knowledge base applies -> propose candidate solutions
         -> extract the knowledge and methods used by each solution -> check for boundary violations
         -> if a solution violates the boundary, solve again -> return an in-boundary answer

The knowledge base is not just an answer store here. It is a reasoning reference system that affects candidate generation, ranking, and revision.

This difference matters. A new question usually will not appear verbatim in textbooks or historical records, so "there is no direct answer" must not mean "the knowledge base has no role." In many real tasks, the most important role of the knowledge base is not providing the conclusion. It is providing the definitions, methods, precedents, and judgment criteria the AI is allowed to use.

Traditional retrieval and the OpenShelf mode differ in several ways:

• Role of the knowledge base. Traditional retrieval provides text relevant to the question. OpenShelf makes the knowledge base influence which directions the AI should think in.
• When a direct answer is found. Both modes can cite the source text and answer directly.
• When only related material is found. Traditional retrieval usually passes the material as context, or reports insufficient evidence. OpenShelf uses related knowledge, methods, and precedents as both generation guidance and an audit boundary.
• When there is no ready-made answer. Traditional knowledge-base work is mostly done. OpenShelf can still let the AI combine in-corpus primitives, then adjust based on audit results.
• Final goal. Traditional retrieval looks for the answer in the knowledge base. OpenShelf looks for the answer the user is more likely to accept.

The key point is not making search feel more like chat. It is making search results change the later reasoning. related_only is not a passive failure state. It is a control signal: the knowledge base cannot directly answer, but it has already supplied the boundary the AI should respect while thinking.

3. Three retrieval states, three reasoning modes

OpenShelf uses supported, related_only, and not_found to distinguish how the knowledge base participates in a task.

supported: the knowledge base can answer directly

The knowledge base contains sufficiently direct textual evidence. For example:

• "How does the textbook define derivative?"
• "What does Proposition 3 in this paper say?"
• "Why did the owner reject this compute plan last time?"

In this state, the agent should answer from the original text, pages, and citations. This is the same as a standard database question-answering product.

related_only: there is no ready-made answer, but the knowledge base defines the reasoning boundary

A new math problem usually belongs here. The textbook does not contain the final answer, but it contains the definitions, theorems, and problem-solving methods that may be used.

Here, related_only should not mean stopping, and it should not mean immediately ignoring the knowledge base and answering freely. It means the agent should enter an "in-boundary reasoning" mode:

1. Generate candidate solutions.
2. Extract the key skills used by the solution.
3. Check those skills against the knowledge base.
4. If all are supported, return the solution.
5. If some skills are out of boundary, solve again using the violations as feedback.

In math and research settings, a skill means a theorem or problem-solving idea. In programming settings, it can represent the user's habits and style.

not_found: the knowledge base is not materially related to the task

If a math textbook knowledge base receives "help me write a birthday invitation," forcing it to find evidence in the textbook is pointless. The agent can return to ordinary reasoning.

But not_found must not mean a single keyword retrieval missed. The system should avoid bypassing the knowledge boundary because of synonyms, translation, or recall failure. More precisely, not_found should mean that after query rewriting and necessary supplementary retrieval, there is still no sign that this knowledge base applies to the current question.

4. Why OpenShelf needs both page chunks and technical chunks

OpenShelf does not simply split PDFs into one fixed chunk size. It needs to answer two different questions:

1. Where does the source say something, and what does it say?
2. Which knowledge primitives can the agent use for reasoning?

That is why page chunks and technical chunks have different jobs.

• Page chunk. This layer answers "where is the original text and what is its context?" It stores page numbers, body text snippets, neighboring chunks, and document metadata. It is useful for BM25 recall, direct evidence, citations, and page review.
• Technical chunk / result. This layer answers "what reusable object is defined or proven here?" It stores type, label, statement, assumptions, conclusion, proof, formula references, and related definitions. It is useful for method search, knowledge-primitive identification, and boundary checks on candidate solutions.

4.1 Page chunk is the evidence-location layer

Normal ingestion first preserves PDF page text and produces overlapping chunks with page numbers. It is good for answering:

• Which page mentions these concepts?
• What is the surrounding context?
• Which page should this answer cite?
• Can the retrieval result be verified against page text or page images?

The core value of page chunks is faithful preservation of source text and location. They do not try to decide whether a passage is a definition, assumption, theorem, or proof in the logical structure.

4.2 Technical chunk is the reasoning-primitive layer

For mathematics, economics, and other theoretical documents, fixed-length chunks break the boundaries of knowledge objects. A theorem's assumptions may be in one paragraph, its conclusion in another, and its proof across several ordinary chunks. A mention of "Proposition 3" in the body should not be confused with Proposition 3 itself.

OpenShelf can therefore recover structured technical results from the pages and chunks already ingested, including:

{
  "result_type": "theorem | lemma | proposition | definition | assumption",
  "result_label": "Proposition 3",
  "page_start": 18,
  "page_end": 19,
  "statement_text": "...",
  "assumption_text": "...",
  "conclusion_text": "...",
  "proof_text": "...",
  "formula_refs": ["(6)", "(21)"],
  "related_definitions": ["Definition 2"],
  "chunk_ids": ["...", "..."]
}

This is not a "smaller page chunk." It is a different data object: a knowledge unit that can be retrieved, cited, checked for prerequisites, and used by later reasoning.

A technical result still keeps page_start, page_end, and the original chunk_ids, so the structured object does not sever the evidence chain. An agent can find a theorem first, then return to the corresponding page chunk, full page text, or even a page image to verify the source.

The current implementation also reserves lineage interfaces for source_links, derived_from, relation_candidates, and technical-result links, so future systems can express that a proposition in one paper uses a theorem from a textbook, or that a conclusion depends on a specific definition or formula.

4.3 Why both indexes are necessary

With only page chunks, the system can find "pages that discuss derivatives," but it is hard to judge which theorem a candidate answer used and what conditions that theorem requires.

With only technical chunks, the system loses full context, ordinary exposition, and reliable page location.

The two layers therefore carry different responsibilities:

Page chunk       = evidence, context, and provenance
Technical result = usable and auditable knowledge primitive

OpenShelf's reasoning boundary depends on the connection between the two, not on any single chunking strategy.

5. From retrieval to generate, audit, and rewrite

OpenShelf is built for agents with MCP tools. MCP retrieves, returns structured knowledge objects, and audits method boundaries. Candidate solution generation and rewriting still belong to the agent.

flowchart TD
    A["User question"] --> B["Search OpenShelf"]
    B --> C{"Relationship between knowledge base and question"}

    C -->|"supported"| D["Answer from direct evidence"]
    C -->|"not_found"| E["Use ordinary reasoning mode"]
    C -->|"related_only"| P["Retrieve usable knowledge primitives and similar precedents"]
    P --> F["Generate and rank candidate solutions"]

    F --> G["Extract method and resource list"]
    G --> H["Audit against the knowledge base"]

    H --> I{"Audit result"}
    I -->|"passed"| J["Return in-framework answer"]
    I -->|"failed"| K["List out-of-scope knowledge or preference violations"]
    K --> L["Lower priority of violating directions and rewrite"]
    L --> F
    I -->|"uncertain"| M["Ask user for clarification"]

6. Hard constraints belong in prompts; the knowledge base should store soft boundaries that are hard to state

The knowledge base is not the best place for every constraint.

If a rule is explicit, stable, and mandatory, the most direct approach is to put it in the system prompt, agent policy, or current task prompt:

Do not call paid GPUs without confirmation.
A single task may run for at most 30 minutes.
Do not reveal customer data in the answer.

These hard constraints should not depend on retrieval hits. They should apply consistently to every task.

OpenShelf is more valuable for storing soft preferences, habits, and contextual judgments that are difficult to describe all at once. They usually have these properties:

• The user cannot easily summarize them as a concise rule.
• Turning them into a prompt would require many qualifiers and exceptions.
• The same choice has different meaning under different data sizes, deadlines, and resource conditions.
• The user has not stated the preference explicitly, but shows a stable tendency through repeated approvals, rejections, and revisions.

For example, suppose a user rejected a Python for loop plan expected to run for four hours and asked for a parallel implementation. That does not mean "the user forbids loops forever." A more useful memory is:

{
  "task_context": "large-scale data processing",
  "proposed_plan": "Python serial for loop",
  "estimated_runtime": "4 hours",
  "user_decision": "rejected",
  "requested_revision": "parallelize the computation",
  "preference_signal": "prefers parallel or vectorized approaches for large, long-running tasks"
}

Next time a similar task appears, the agent can retrieve these precedents before presenting a plan. It can ask whether the current serial implementation will again run too long, and whether it should first use batching, vectorization, or parallelism.

If the user mainly works with AI through Vecbase, tasks, candidate plans, resource estimates, user approvals or rejections, revision requests, and final accepted plans can all be continuously distilled into structured memories like this. Over time, the knowledge base becomes a model of personal working style that would be hard to write in one prompt.

It is not a static "user preference list." It is a set of contextual decision precedents. Historical approvals can help predict user preferences, but they cannot automatically grant new resource authority. The agent may optimize its plan based on precedent; if a new task involves new cost, permission, or risk, it should still ask for explicit user approval.

7. How OpenShelf currently implements this infrastructure

The current public implementation of OpenShelf focuses on local PDF knowledge bases:

• One knowledge base corresponds to one physical DuckDB file.
• Multiple knowledge bases are isolated by db_name; there is no implicit union search.
• PDF page text, page chunks, and term statistics are stored in DuckDB.
• The default retrieval layer uses DuckDB-backed BM25 for explainable text search.
• search and search_terms return supported, related_only, or not_found.
• build_technical_index can preview or write structured technical results.
• search_technical_results can retrieve theorems, definitions, propositions, assumptions, proofs, formula contexts, and nearby definitions.
• check_reasonable can extract technical methods from a candidate answer and check whether those methods exist in a closed corpus.
• get_chunk, get_page_text, and get_page_image return to the original evidence.

Normal ingestion automatically creates page chunks. Technical results are an on-demand second-layer index: by default they can be dynamically extracted and searched in read-only mode. They are written to the optional technical_results table only when both dry_run: false and write: true are set explicitly.

7.1 One DuckDB file is one portable knowledge boundary

OpenShelf chooses DuckDB partly because a knowledge base does not need a continuously running database service. Document metadata, page text, page chunks, term statistics, and optional technical results can live together in one .duckdb file.

This makes the knowledge base close to a portable product unit. Copy the .duckdb file to another machine or another user, register it with create_db_from_exist, and it can be used directly without parsing and indexing all the material again.

Knowledge boundaries can then be standardized, combined, and distributed. For example, one could build:

• a People's Education Press high-school mathematics knowledge base;
• variants for arts track, science track, or different regional curricula;
• AP Calculus or IB Mathematics knowledge bases;
• an industry standard operating manual knowledge base;
• a knowledge base for classic papers and handbooks in a research direction.

Users can start with a standard knowledge base, or create a personal version from the textbooks, handbooks, papers, and work materials they have actually read. The same question can then receive different but reasonable answers under different knowledge bases. The difference does not come from a random prompt. It comes from the knowledge range the user chose.

8. Conclusion

A personal knowledge base should not merely let AI search and remember more facts. Hard constraints can be written directly into prompts. What truly needs a long-term knowledge base is the set of contextual, hard-to-state soft boundaries that only emerge through repeated interaction.

Page chunks let the system return to the source. Technical results let the system identify and audit reusable knowledge primitives. Together, they make the knowledge base more than a search component. The knowledge base can participate in agent generation, checking, and rewriting.

OpenShelf is built on a simple judgment:

A knowledge base should not only tell AI "what is here"; it should also influence "where to think next."