Personal Knowledge Bases

Keep a reusable local library of documents, datasets and media. TensorSharp.Knowledge retains original files and indexes searchable excerpts with source locations. TensorAgent adds collection management, folder uploads, saved-chat imports, previews and per-chat selection; supported server chat APIs and agent tools use the same store.

This guide describes current source. Personal knowledge and response steering were added after v2026.10.10; use a newer build containing them. A release tag or successful package build alone does not establish model, OCR or device validation.

Create a library and use it in a chat

1. Create a collection

   Open Menu → Knowledge, enter a name and select Create. Collections keep their identity when renamed.

2. Add sources

   Choose Upload files or Upload folder. Folder imports include nested folders and retain relative paths. The app uses a native folder picker; the browser uses its directory picker. Progress and per-file failures are visible. Originals remain in the library after chat or upload-cache cleanup.

3. Bring in saved conversations

   Add chats opens a searchable history picker. Select up to 32 saved chats across pages and choose Add and index selected chats. User and assistant messages, available attachments and produced files are indexed; private reasoning is excluded. Missing files are reported. Reimporting refreshes stable source paths without duplicating unchanged files. This is a snapshot: later conversation changes require another import.

4. Check extraction

   Browse counts, filename/path and type filters, sort order and file pages. Inspect each source's status and warnings. Search within a collection, use Read surrounding context, or open indexed text and supported original previews. Download original returns the retained source.

5. Select a chat scope

   Check Use {collection} in this chat or its checkbox in the collection catalog. Selected chips appear above the composer. Up to 32 collections can be selected; a new chat starts with none, while saved chats restore their selection. Browsing, importing and reindexing do not select a collection for inference.

6. Ask with evidence

   Relevant excerpts are retrieved before the reply. Tool-capable models can refine searches, expand context and open originals for analysis, subject to the host's evidence and tool budgets. For a dataset calculation, ask the agent to open the complete original and run code rather than treating a few retrieved rows as the whole dataset.

What becomes searchable

Ready means the extractor produced content without a declared coverage warning; Partial records limitations; MetadataOnly indexes the filename only. Generated descriptions and transcripts always remain partial. Reindexing uses the retained original with the currently available extractors and embedding provider.

PDF OCR runs on the host

Supported Apple hosts use CoreGraphics and Apple Vision, with no separate installation. TensorAgent on Windows and its Linux core host automatically prepares private Poppler/Tesseract tools and pinned English and simplified/traditional Chinese language data when a page first needs OCR. Text-only PDFs do not trigger that download. Setup progress and retry are visible; a setup failure preserves an existing committed document. OCR then runs locally, including on mixed pages with both selectable text and scanned content.

The default budget is 128 OCR pages per document, 16,777,216 rendered pixels per page and a 60-second page deadline. Recognition and platform coverage remain separate from successful setup. There is no shipped Linux MAUI desktop application; standalone Windows/Linux hosts must configure tools or opt into the provisioner. Browser previews use the connected host's OCR.

Retrieval, citations and retained originals

Default retrieval uses local BM25 text search with Unicode-aware terms and CJK n-grams. Optional GGUF sentence embeddings add exact cosine search; reciprocal rank fusion combines lexical and semantic rankings. Chat hosts can apply one bounded relevance pass with the loaded model; TS_KNOWLEDGE_RERANK=0 disables it. Invalid output or timeout keeps the original order. These methods search extracted text, including media captions, rather than raw media embeddings.

Retrieved sources shows only retrieved identities actually cited in the final answer. Source links open the cited excerpt or original preview; image/video sources can show thumbnails and video sample times. Citation markers such as [K1] bind to host-issued identities. Unknown or stale markers do not create source chips. Correct identity does not prove every claim in the answer.

Originals are SHA-256-addressed; importing the same relative filename and bytes is idempotent. Changed files or reindexing advance the version. Only the current version is retained, so old citations fail as stale rather than opening changed content. Failed extraction or embedding preserves the previous committed source. The store is an embedded, single-writer personal library.

Defaults include 64 MiB per file, 2 GiB logical source storage, 100 collections and 10,000 documents. Indexes and temporary files need additional disk/memory. Automatic retrieval has bounded excerpts and tool calls. Strongly identified single-document evidence can expand to a complete indexed-text snapshot only after the actual prompt and answer allowance pass the model-context fit check; otherwise ordinary retrieval remains. A complete indexed-text snapshot does not establish complete extraction.

Standalone server and agent integration

Set TS_KNOWLEDGE_DIRECTORY before starting TensorSharp.Server.Host to opt into the store and /api/knowledge routes. Optional TS_KNOWLEDGE_EMBEDDING_MODEL, TS_KNOWLEDGE_EMBEDDING_BACKEND, TS_KNOWLEDGE_QUERY_PREFIX and TS_KNOWLEDGE_DOCUMENT_PREFIX configure a separate local encoder. Changing its identity requires reindexing for semantic search; old documents retain lexical retrieval.

TS_KNOWLEDGE_DIRECTORY="$PWD/library" \
dotnet run --project TensorSharp.Server.Host -- \
  --model /path/to/chat-model.gguf --backend ggml_metal --port 5000

Management includes collection creation/deletion, document listing/upload/deletion/reindexing, POST /api/knowledge/search, POST /api/knowledge/read and versioned original downloads. The standalone upload accepts one multipart file per request. Search/read use explicit collectionIds. TensorAgent additionally supplies rename, folder/chat import and preview UI routes; these are not all standalone-server endpoints.

Supported inference routes use the exact camel-case field knowledgeCollections: TensorAgent/WebUI POST /api/chat, standalone POST /v1/chat/completions, POST /v1/responses, POST /api/chat/ollama, and POST /api/generate. Ollama generate supports retrieval and citations without an agent tool loop. Empty or missing selection retrieves nothing; invalid/deleted selections are rejected. The ordinary TensorAgent host does not expose every standalone compatibility API.

{
  "model": "chat-model.gguf",
  "messages": [{ "role": "user", "content": "Compare the findings in these documents." }],
  "knowledgeCollections": ["collection-id"],
  "stream": false
}

OpenAI/Ollama replies expose knowledge_sources, knowledge_citation_repairs and bounded knowledge_tool_steps metadata when knowledge is selected. Streaming compatibility adapters buffer final answer text for citation binding before emitting append-only answer deltas; reasoning and tool activity can arrive earlier. tool_choice: "none" keeps retrieval while disabling agent tools. Tool-capable hosts provide knowledge_list, knowledge_search, knowledge_read and knowledge_open; the last can copy the complete original into an enabled private code workspace.

Keep remote management behind the application's authentication boundary. Collection IDs define retrieval scope and are not authorization credentials. The bundled standalone server Chat page has no TensorAgent collection-management panel; use the API or SDK there.

Coverage and validation

The repository includes store/extractor, host integration, scope/citation, chat import, browser UI, OCR and live-model tests and probes. Test presence, fixture tests and package builds do not certify every extractor, codec, model or device. Skipped/unavailable scenarios are unvalidated. Small clean media and synthetic scans are correctness diagnostics, not general answer-quality, OCR-accuracy or throughput benchmarks.

See the full knowledge design and configuration guide and validation procedures and platform limitations. Review generated answers against originals separately from citation checks.