Knowledge Vault answers questions using work you have already done. Each answer cites the session, note, or document it used.
Everything happens inside Claude Code except creating an OpenAI key.
01Before you install
- Accept the GitHub invitation from your email or GitHub notifications.
- Add credit to your OpenAI account.
The invitation gives your GitHub account read access to the plugin repository, and nothing else. Until you accept it, your account cannot see the private repository, and the install command stops without an obvious fix.
Indexing and searching use billed calls from your OpenAI account. A key without credit authenticates, then fails during the first index.
02Install the plugin
Run both commands inside Claude Code. The first registers the Tenkr marketplace. The second installs the plugin from the private repository.
The @tenkr-plugin-marketplace suffix tells Claude Code which marketplace contains the plugin.
// 1. Register the Tenkr marketplace /plugin marketplace add TenkrAS/tenkr-plugin-marketplace // 2. Install the plugin (the @marketplace suffix is required) /plugin install knowledge-vault@tenkr-plugin-marketplace
03Set up your project
1. Connect the plugin
Run setup from the project you want to search.
/knowledge-vault:setup
setup asks whether to create a folder for your documents.
- Say yes to choose its location.
setupcreates the folder and records it asKV_KNOWLEDGE_DIRin.envat your project root. - Say no to use the documents folder included with the plugin.
setup writes only the folder you choose and the settings file. It asks for consent before both actions. It is safe to re-run.
2. Create an OpenAI key
- Open the OpenAI API keys page and sign in.
- Create a secret key with a recognisable name, such as
knowledge-vault. - Copy the key when it appears.
- Confirm that the account has credit.
OpenAI shows the full key once. Create another if you lose it.
3. Run the health check
/knowledge-vault:doctor
The doctor command checks the plugin's requirements and reports anything missing. It asks for permission at most twice.
On its first run, it offers to install its toolchain. This includes uv, Python 3.12 or newer, and the plugin's packages.
The toolchain uses its own machine-wide cache. It does not install into your project or the plugin folder. You do not install anything by hand.
If the OpenAI key is missing, doctor offers to create an empty .env at your project root. The file is already ignored by git.
doctor never asks for, prints, or stores your key. It is safe to re-run.
4. Add the OpenAI key
Open .env at your project root. Paste the key on the OPENAI_API_KEY line.
Run doctor again. It confirms that the key is readable before you spend anything on indexing.
The plugin reads OPENAI_API_KEY and no other name. It does not read a near-miss such as OPENAI_KEY.
If a similar name already exists, doctor flags it so you can rename it.
5. Build the index
/knowledge-vault:index
index reads your sessions, project memory, and documents. It builds the catalogue used by search.
The first run reads everything. Later runs are incremental and process only changed material.
index previews the cost and waits for your approval. It does the same before rebuilding the catalogue from scratch.6. Search your work
Ask a plain question in quotes. There is no keyword syntax.
/knowledge-vault:search "what did I decide about pricing?"
search builds an answer from matching material and includes citations.
04Confirm it works
Ask about a decision that exists only in your own history.
/knowledge-vault:search "why did we drop the second pricing tier?"
A working result cites the session, note, or document containing the answer. Open the source to confirm the answer.
If the answer has no citation, run /knowledge-vault:index, let it finish, and search again.
If the citation points to irrelevant material, the answer was not stored in a source the plugin reads. It can also be in a documents folder you have not connected.
05What Knowledge Vault reads
Knowledge Vault searches three sources already on your machine:
- Past sessions. Claude Code history for this project. A cleaned copy is saved when each session ends. It survives Claude Code's 30-day cleanup of raw transcripts.
- Project memory. The assistant's memory store for this project. The plugin reads it and never writes to it.
- Your documents. Reference material from the folder you choose.
setupcan create and connect this folder with your consent.
These sources support questions you would otherwise answer by searching through weeks of sessions.
06Read PDFs, Office documents, and images
Text files require no extra setup. PDFs, Office documents, and images require a Mistral key.
Skip this setup if your documents folder contains only plain text and markdown.
Run doctor with the reading flag:
/knowledge-vault:doctor --ocr
If MISTRAL_API_KEY is missing, doctor offers to add a placeholder to the same git-ignored settings file. Paste the key there yourself.
If it finds a near-miss such as MISTRAL_KEY, it flags the name so you can rename it.
You enable document reading during indexing. The index command documents that option.
Without document reading, text files still index. Binary documents are skipped with a clear notice instead of being indexed as empty files.
07Keep the catalogue current
The catalogue is a snapshot from your last index.
| Command | Use it when |
|---|---|
search | You need to remember something. |
index | You added material that needs to be searchable. |
A session from this morning remains invisible to search until you index again. An empty result for recent work usually means the plugin has not indexed it.
index at the end of a working session. Your catalogue is current when you return, without delaying your first search.Updates require no new setup. Your one-time purchase includes lifetime updates through the same install command.
08Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Install cannot find or reach the plugin. | The GitHub invitation is still pending. | Accept it, then run the install command again. |
doctor reports no key. | The key name or .env location is wrong. | Use OPENAI_API_KEY in .env at your project root. |
| The first index fails. | The OpenAI account has no credit. | Check the account balance and add credit. |
| Search returns nothing relevant. | The catalogue is missing or outdated. | Run /knowledge-vault:index, wait, then search again. |
| The first index appears idle. | It is reading everything from scratch. | Let it finish. Later runs process only changes. |
| The index shows a cost preview. | It is waiting for your approval. | Approve the cost to continue. |
09Privacy and storage
The index lives on your machine. It is scoped to one project and stored outside your repository. Indexing does not add anything to your git history.
Captured copies of past sessions sit beside the index. They are never uploaded.
Text leaves your machine only in these cases:
- OpenAI receives material used to build the index.
- Mistral receives PDFs, Office documents, and images when you enable document reading.
Tenkr never receives your project, files, searches, OPENAI_API_KEY, or MISTRAL_API_KEY.
You own both external accounts. OpenAI processes material under the key you created and your agreement with OpenAI. Mistral processes enabled documents under your own Mistral key.
The plugin never writes to project memory. It asks for consent before creating the documents folder or settings file.
Your OpenAI dashboard shows the plugin's spending. Revoking the key cuts off its access completely.