Aura Terran Knowledge user guide

What it is

Aura Terran Knowledge is a Windows application that turns folders of your own documents into a searchable knowledge base on your PC. You point it at folders, it splits and indexes them locally, and you search them from the app or let your AI tools search them for you. Each collection is a namespace — a separate knowledge base with its own documents and settings.

Your tools reach that knowledge three ways, all on your machine: an MCP server that Cursor or Claude Desktop can call, a local Management API for scripts, and optional passthrough listeners that accept a normal chat request, add relevant passages, and forward it to the model you configure. The app also includes tools to check retrieval quality — Grounding, Retrieval Lab, and Conflicts — so you can see whether answers are supported by your documents.

Aura Terran Knowledge does not host a model of its own and does not upload your documents. Search and indexing run on your PC; a model is involved only if you connect one.

Prerequisites

Hardware

• Operating system — Windows
• Memory — 32 GB RAM
• Processor — Intel Core i7 or equivalent
• GPU (optional) — NVIDIA RTX 3090 or equivalent recommended when using Ollama for local models

Software

• Windows — download the installer from the download page
• Documents to index — folders or files (PDF, Word, Excel, CSV, HTML, Markdown, plain text, and common source and config files)
• Network access on first index — the app downloads its on-device embedding model once (see Privacy and data); after that, indexing and search work offline
• Optional: an MCP client (Cursor, Claude Desktop) if you want your agent to search your documents
• Optional: Ollama or an OpenAI-compatible API if you turn on a chunking LLM or passthrough

Installation

Download the latest Windows installer from the download page (currently v1.12.30). It is digitally signed as Halo Softworks LLC, our registered company name; the download page shows the checksum if you want to verify it.

1. Run AuraTerran-Setup-1.12.30.exe
2. Read and accept the EULA, choose the install folder if you want a different one, and finish. No administrator prompt is needed for the default per-user location
3. Launch Aura Terran Knowledge from the Start menu. The first launch starts a 14-day trial of the whole product — no key, no card, no account

The app keeps itself current: while it is running it checks our release feed about every four hours, downloads a new version in the background, and installs it the next time you close the app.

Configuration

Day-to-day settings live in the app under Settings; you do not need to edit files.

• General — tray behavior, start with Windows, indexing performance
• Chunking — how documents are split, and an optional chunking LLM
• Retrieval — hybrid search, how many results, score thresholds, reranking, and always-inject files
• Management API — port (default 41800), auto-start, and the bearer token scripts must send
• Passthrough — OpenAI- and Ollama-compatible listeners that add context and forward to your upstream model (trial or paid license)
• MCP Server — the inbound rag_search tool for IDE clients (default port 41801), with one-click setup for Cursor and Claude Desktop
• External MCPs — third-party tool servers used alongside retrieval in passthrough (trial or paid license)
• Web search — optional web results blended with your documents (trial or paid license). When on, your query goes to the web search provider
• License — trial status, and where to activate a purchased key

All listeners bind to 127.0.0.1 only and require the bearer token by default; /health is open so tools can check the app is up.

Adding documents

Use the Ingestion tab to point Aura Terran Knowledge at folders or files and pull them into a namespace (for example work-docs or personal-notes).

1. Create or select a namespace
2. Add folders or files — the app splits them into passages and builds the index on your PC
3. Wait for indexing to finish (the Vector Store view shows progress), then search

Each namespace is isolated: its own documents, index, and retrieval settings. The trial and paid license allow unlimited namespaces and root folders; the post-trial evaluation mode is limited to one namespace and up to three root folders.

Optional chunking LLM

Core search uses an on-device embedding model and does not need OpenAI or Ollama. Optionally, under Settings → Chunking, you can point at Ollama or an OpenAI-compatible API to refine where documents are split. That runs at index time only, and it means passages of your documents are sent to that model — local Ollama keeps them on your PC; a cloud API does not.

At answer time you can either point OpenAI- or Ollama-shaped clients at the app’s passthrough listeners (the app adds relevant passages, then forwards to your upstream model), or call the Management API or MCP for ranked passages only and run the completion in your own client.

Running the app

Start Aura Terran Knowledge from the Start menu. The Server tab shows the status of each local service:

• Management API — search, ingest, and admin over HTTP for scripts
• Passthrough — OpenAI / Ollama listeners that add your documents’ context to chat requests
• MCP Server — rag_search for Cursor, Claude Desktop, and other MCP clients
• External MCPs — third-party tools used alongside retrieval (trial or paid license)

Copy the bearer token from Settings before calling the API or MCP from scripts. The app can run in the tray so your tools can reach it while you work.

Using retrieval

Pick whichever path fits the tool you are using:

• Search UI — search and tune inside the app
• MCP — let Cursor or Claude Desktop call rag_search against your namespace (one-click setup under Settings → MCP Server)
• Passthrough — point an OpenAI- or Ollama-compatible client at the app (trial or paid license); it adds relevant passages and forwards to your configured model, then scores the reply against those passages in Grounding
• Management API — POST /admin/corpus-search returns ranked passages for scripts and custom agents
• Retrieval Lab — compare two retrieval configurations on a saved question set before changing settings
• Conflicts — find near-duplicate passages that disagree before a stale copy answers a question

Retrieval quality depends on your documents, how they are split, and your prompts. For decisions that matter, check the source document; the app shows you which passages were used so you can.

Works with Aura Wire (optional)

Aura Terran Knowledge is a standalone product. If you also use Aura Wire AI Command Center, its Terran stage can pull relevant passages from your namespace into every Wire chat without changing your editor’s settings. The bridge entitlement is included with any paid Terran license and with the Aura Wire AI Command Center license; the Terran trial and post-trial evaluation mode do not include it, and buying Wire does not include Terran.

1. Keep the Management API enabled here (default http://127.0.0.1:41800)
2. In Wire, open Pipeline → Aura Terran → Connection, enable the stage, and set the URL, namespace, and search options
3. Watch Wire’s Live Traffic: it shows whether each turn was enriched or skipped, not the passage text

The connection is loopback-only on your machine. See the Wire Terran bridge for the Wire side. If Terran is offline, Wire forwards the chat without injection.

Privacy and data

Aura Terran Knowledge is built so that your documents stay on your PC. That is how it behaves today; it is a design choice, not a guarantee against every possible misconfiguration, and any model, web search, or external tool you connect receives what you send it under that service’s policies.

Stays on your PC

• Your documents and the index — split, embedded, and stored under %USERPROFILE%\.aura-terran. Nothing is uploaded to Bitfield Creek Labs
• Search queries and results — handled locally. A local request log records API calls to the app for your own troubleshooting
• Settings, license, and tokens — kept in the same folder

Leaves your PC

• Embedding model download — on first index the app fetches its on-device embedding model files from huggingface.co, once. Only model files come down; none of your content goes up
• Models and services you connect — a chunking LLM receives document passages at index time; a passthrough upstream receives the chat plus injected passages; web search receives your query; external MCP tools receive what the request gives them. Local Ollama keeps all of that on your PC; cloud services do not
• Update checks — the app reads our release feed about every four hours while running and downloads new versions in the background
• License and trial — the trial start and a key activation send the product, a random device identifier, the app version, and (for activation) your key to our license server. The stored license then works offline
• De-identified operational events — install succeeded (from the installer), session start and end with approximate run time, and one uninstall notice, each with app version, an OS label, and a random device identifier. No document names, paths, or query text
• Crash reports — only if you click Send on the error screen; they contain sanitized error text with user paths removed

The Privacy Policy describes these events and the website in full. If something here does not match what you see, tell us.

Troubleshooting

First index never finishes or reports a model error

The one-time embedding model download needs access to huggingface.co. Check that a firewall or proxy is not blocking it, then retry; once cached, indexing works offline.

Indexing fails or hangs

Check disk space and file permissions. Review the in-app logs and the Server tab.

No results or poor answers

Confirm the right namespace is active and indexing finished. Adjust chunking and retrieval in Settings, and use Retrieval Lab to compare before committing a change.

Cursor, Claude Desktop, or a script cannot reach the app

Verify the listener is enabled, the port matches your client config (MCP default 41801, Management API default 41800), and you are sending the bearer token from Settings.

Chunking LLM errors

Check the Ollama or OpenAI-compatible base URL and model name under Settings → Chunking. Retrieval works without a chunking LLM.

Windows says the publisher is unrecognized

Bitfield Creek Labs is a newer publisher, so SmartScreen may show a warning. Do not turn SmartScreen off; check that the digital signature is valid and the publisher shown is Halo Softworks LLC (our registered company name, which is what the certificate carries), or compare the checksum on the download page. See Secure Windows downloads.

Bugs and feature requests

Contact Bitfield Creek Labs with steps to reproduce, versions, and error messages.

Known limitations

• Windows is the only supported platform today
• The on-device embedding model is downloaded on first index, so the very first index needs network access
• Retrieval quality varies with document quality, chunking, and namespace design
• Generated answers should be checked against the source for anything important
• Large libraries may need tuning of chunk size, hardware, and retrieval settings

For the product overview, see the Aura Terran Knowledge product page.