Known limitations.
A knowledge base is chosen once and lived with for years, so the parts that are missing decide the choice as much as the parts that work. This page is the list of things Hadano AI Cabinet does not do in the build the rest of this site describes. Every entry was checked against the implementation rather than against an intention: where a capability is named in the interface but refused at runtime, that is said here in those words. Nothing below is scheduled, because a date would be a promise this page is not in a position to make.
Not available in the current build
These are capabilities a reader can reasonably expect from a knowledge database and will not find. Not in this build means the code refuses the request, or the path exists and does not reach a working result. Not published means the code runs but nobody outside can obtain it yet.
| Capability | Status | Note |
|---|---|---|
| Semantic (embedding) search | Not in this build | Vector storage exists in the engine but is not reachable from the tools in this build. HADANO_EMBEDDINGS accepts only off; any other value stops the server at startup with the reason, rather than being accepted and quietly ignored. Asking search_knowledge for vector or both returns E_VALIDATION. Keyword search and graph expansion are unaffected. |
| Reading PDF, Office, image, audio, or video files | Not in this build | A document is a title and a text body. Binary content has nowhere to go in the file format, so extraction to text happens in the AI client before storing. The database never opens a binary and never executes what it holds. |
| Backup and JSONL dump / restore commands | Not in this build | Neither command works against the current storage engine, so neither should be relied on. Until they do, a backup is a copy of the database file taken with the server stopped — which the single-file design makes a complete one. |
| An installable package | Not published | There is no release on a package index, so pip install hadano-ai-cabinet does not work today. The machine-readable form of this is installable: false in /facts.json. Implementation status and availability are separate things, and this site keeps them separate. |
| Concurrent writers, or readers alongside a writer | Not in this build | The file takes an exclusive lock when it is opened, and tool calls are serialised behind it. A store call blocks queries until it finishes, and a single document may be up to one megabyte of text. Two clients sharing one audit file can also lose lines from it. This is a design choice rather than an oversight — it is what keeps “the file is the database” literally true — but it is a hard ceiling, not a tuning knob. |
| HTTP API, SDK, or user interface | Not in this build | Seven callable tools over the Model Context Protocol on standard input and output, and nothing else. Anything that is not an MCP client has no way in. |
| Hosted or multi-user service | Not in this build | Everything runs on your own disk. There is no account, no endpoint, and no shared instance, and none is offered today. |
| Reclaiming disk space after deletion | Not in this build | Space freed by a deleted document returns to a free list inside the file and is reused, but the file itself never shrinks. A knowledge base that churns will keep growing. |
| Erasing deleted content from the file | Not in this build | Deleting a document removes it, its chunks, its index entries and its edges in one transaction, so it disappears from search and from get_document. The old bytes are not overwritten and can still be read out of the file until that space is reused. If the content has to be unrecoverable, full-disk encryption is the layer for it. |
| Interrupting a query already inside the engine | Not in this build | The per-call budget of 2,000 ms is checked at stage boundaries, so a call that has entered the engine runs to completion rather than being cut short. On the corpora measured here that distinction has not mattered; on an adversarial input it would. |
| Whole sentences as search queries | Not in this build | Query text is split on whitespace; each term is matched as a substring through the character-trigram index, and the terms are combined by adding their BM25 scores, so a document matching more terms ranks higher. Two consequences worth knowing: a term shorter than three characters is skipped while a longer term is present, and a sentence written without spaces — ordinary in Japanese — is matched as one long phrase and usually finds nothing. Give the search a few content words instead. |
Validated platforms
The storage engine is C and needs a build for each platform. One platform has actually been built and run.
| Platform | Status |
|---|---|
| Windows 11 x64 — MSVC, Python 3.14 | Tested |
| macOS | Planned |
| Linux | Planned |
| ARM | Planned |
Tested = the engine was built there, the whole suite ran green, and it has stayed green there since 2026-08-20. Planned = decided and not yet done. Nothing here carries the label Experimental, because no build on those platforms has been produced to try.
Read the three Planned rows strictly. They do not mean “probably fine”: no machine has compiled the engine on macOS, Linux, or ARM, and no test has run there. The POSIX build path has been checked only by reading it against the Windows one, which catches a missing source file and cannot catch anything a compiler or a filesystem would. The published measurements below were all taken on the tested platform, so they carry the same restriction.
The Python side is ordinary: Python 3.11 or newer, with two runtime dependencies. It is the engine underneath that is platform-specific.
What the benchmark numbers do not mean
Retrieval quality is measured on public corpora so that anyone can repeat it. Here is what those runs cover, and the limits of what they support.
| BEIR corpus | nDCG@10 | Published Lucene BM25 | Queries returning nothing |
|---|---|---|---|
| SciFact — 5,183 docs, 300 queries | 0.5800 | 0.665 | 0 / 300 |
| NFCorpus — 3,633 docs, 323 queries | 0.2733 | 0.325 | 22 / 323 |
Measured 2026-08-27 on Windows 11 x64, Python 3.14, embeddings
off, top_k=50, over the full test split of each corpus. Two runs on
the same day gave identical quality figures. The Lucene BM25 column is the
published score for the same splits (k1=0.9, b=0.4), recorded here on 2026-08-26
as the reference point.
They are two corpora, not a general claim. Both are English, both are scientific or medical writing, and both hold a few thousand documents. A different corpus — a support archive, a code base, a legal collection — can score materially differently on the same engine, and this page has no evidence about yours.
The reference column is there on purpose. A well-tuned keyword baseline scores higher on both corpora. The figures here are close enough to be useful and are not the best keyword retrieval that exists; if ranking quality is the deciding factor for you, that gap is the number to look at rather than the first column.
Twenty-two queries returning nothing is part of the result. On NFCorpus those are queries whose words do not occur in the corpus at all, and returning nothing is correct for them. It is also a reminder that this is exact substring matching: without meaning-based retrieval, a question phrased entirely in synonyms of the stored text finds nothing, and no ranking metric on these two corpora captures how often that happens in your own material.
No CJK benchmark has been run. The character-trigram index exists so that Japanese and other text without word boundaries can be searched with no morphological analyser installed. That capability has not been measured against a public Japanese retrieval benchmark, so it is a design property here, not a scored one.
Nothing has been measured at scale. The largest published retrieval run covers 5,183 documents. Behaviour at hundreds of thousands or millions of documents is not measured and is not claimed.
Latency is not published at all. The current engine has not been timed on an otherwise idle machine: the runs taken so far were made while the machine carried unrelated CPU load, and two runs of identical code over the same corpus gave median search times 37% apart (2026-08-27, Windows 11 x64, Python 3.14). A timing figure needs a distribution behind it, not a single median, so until that exists this site would rather show nothing.
The small-model retrieval result is a narrow experiment. The comparison between retrieval-fed context and a fully pasted window used a synthetic corpus of 100 facts, a single 0.5-billion-parameter model, and deterministic judging with thresholds fixed before the run. That design is what makes it honest, and it is also what limits it: one model, one corpus size, and facts constructed so the model could not already know them. Each question also named an entity that appears nowhere else in the corpus, so the right document was present in the retrieved context for all 100 questions and could not be crowded out; whether that survives a corpus where candidates compete is untested. It says the mechanism works. It does not predict the margin you would see with a larger model on real documents.
When Hadano is a good fit, and when it is not
A good fit
- One agent on one machine, keeping notes, decisions, and reference material across sessions
- Text you already hold as text, or that your AI client can extract before storing
- Collections in the thousands of documents, living on local disk
- Machines with no network, no API key, and no GPU — nothing leaves the disk
- Work where an answer must point at the passage that supports it, and every call must appear in an audit log
- Keyword retrieval over Japanese and other text without word boundaries, with no analyser to install
- Operators who would rather copy one file than run a service
Not a good fit
- Several people or processes reading and writing one knowledge base at the same time — the exclusive lock makes readers wait behind the writer
- Collections far beyond the few thousand documents measured here, or a base that churns heavily, since the file never shrinks
- Work that needs meaning-based retrieval today — finding a paraphrase that shares no words with the query
- PDFs, Office files, images, or audio with no extraction step in front of the database
- Anything driven over HTTP, through an SDK, or from a user interface
- Deployments that need an installable package now, or a platform other than Windows x64
- Content that must be unrecoverable from the file after deletion, without disk encryption underneath it
- Two-way synchronisation between machines — copying the file carries a state, not a history, so it brings back what was deleted elsewhere
If your situation is in the second list, this is the wrong tool and the honest advice is to use something else. The first list is narrow on purpose: a single file, a single writer, and no network is a small design, and everything on this page is a consequence of keeping it that way.