Search your knowledge from Claude Code#

You work in Claude Code and the answers you need are in your own documents: the handbook, runbooks, decisions written down last month. With the Astralyx knowledge skill, Claude searches your knowledge bases with astra, signed in as you, answers with a citation for each claim, and saves a note to a base only after you have read it and said yes. No server to run and no code to write.

What you need:

Claude Code installed.
astra installed on the same computer (Install the CLI).
A knowledge base with something in it — here handbook from Your company handbook; any base works.
To save notes, a role that may add to the base (knowledge-bases:write-content: workspace editors and admins, the Developer and Analyst presets).

Claude searches as you, in the workspace astra points at:

$ astra login
$ astra use <org>/<workspace>
$ astra metis list
NAME                      STATE       DOCUMENTS   CHUNKS    EMBEDDING           REASON
handbook                  Ready       41          1093      bge-m3              41 documents, 1093 chunks (1 document could not be read: see its documents)

2. Install the skill#

$ astra connect claude-code
installed the Astralyx knowledge skill: /home/ana/.claude/skills/astralyx-knowledge/SKILL.md
Claude searches acme/research as you (astra use … changes it)
In Claude Code, ask something your documents answer, e.g. "what does our handbook say about leave?"

The skill goes to ~/.claude/skills/astralyx-knowledge/, for every project; Claude Code picks it up without a restart. It tells Claude when to search, how to cite, and that saving needs your yes. It pre-approves only the commands that read (astra metis list, search, files, memory): for anything that saves, Claude Code also asks your permission to run the command. The skill's text is short — read it, and change it if you like.

3. Ask a question#

In Claude Code, in any project:

What does our handbook say about expenses for conference travel?

Claude lists your bases and searches the one that fits. You see it run:

astra metis list --json
astra metis search handbook "expenses for conference travel" --top-k 8 --json

Its answer cites the documents it used, as the search returned them — (policies/travel.docx › Travel policy › Conferences), (policies/expenses.pdf, page 4). When the results do not answer the question, Claude says so instead of guessing; ask it to search another base, or with other words.

To check a citation yourself, run the same search:

$ astra metis search handbook "conference travel expenses" -k 3

4. Save a decision as a note#

At the end of a discussion:

Save the decision we just made about conference budgets to the handbook.

Claude shows exactly what it would save: the base (handbook), a title, and the full text — and asks Save this to handbook?
You answer yes. Claude Code asks your permission to run the command (it is not pre-approved); allow it.

Claude runs:

astra metis note handbook --title "Conference budgets" --source model --yes --text "…"

and tells you where it was saved:

saved as notes/saved/2026-10-12-conference-budgets.md in handbook (found by searches after its next pass)

The note is Markdown with its title, date and source, written on the base's machine in the base's own notes; searches find it a few seconds later. --yes is how Claude says you already confirmed: without a terminal to ask on, astra metis note saves nothing without it. Answer anything but yes and nothing is saved.

Facts go to a memory the same way (astra metis remember <memory> … --yes): see A memory for your assistant.

Install the skill in the project instead, and commit it:

$ astra connect claude-code --scope project
installed the Astralyx knowledge skill: /work/handbook-tools/.claude/skills/astralyx-knowledge/SKILL.md
Claude searches acme/research as you (astra use … changes it)
commit .claude/skills/astralyx-knowledge to share it with the project
In Claude Code, ask something your documents answer, e.g. "what does our handbook say about leave?"
$ git add .claude/skills/astralyx-knowledge && git commit -m "Astralyx knowledge skill"

Each person who opens the project needs astra signed in: their searches run as themselves and see only what their role lets them read. Name your bases in the committed skill ("Search handbook for policy questions, runbooks for incidents") so Claude picks the right one first.

Without the command line, or with MCP as well#

No astra on that computer: the skill falls back to the search API with an API token in ASTRALYX_TOKEN (Without the command line).
Astralyx's MCP server too: astra connect claude-code --mcp adds it (then /mcp, astralyx, Authenticate). Its tools go beyond knowledge — machines, runs, models — and its save_to_knowledge_base waits for your approval in the console (Let a model save when asked).

Check that it worked#

astra connect claude-code --print says where the skill is (would write …).
In Metis → Overview, Searches, 7 days counts Claude's searches with everyone else's (counts only: questions are not kept).
astra metis files handbook lists the saved note under saved/.

Clean up#

Delete the folder ~/.claude/skills/astralyx-knowledge/ (or the project's .claude/skills/astralyx-knowledge/). A note you saved is removed with astra metis rm handbook saved/2026-10-12-conference-budgets.md.

Troubleshooting#

Symptom	Cause	Fix
Claude says `astra` is not signed in	No session on this computer	`astra login`, then `astra use <org>/<workspace>`
Claude searches the wrong workspace	`astra use` points elsewhere	`astra use <org>/<workspace>`; the skill follows it
Claude answers without searching	The question did not look like one your documents answer	Ask "search my knowledge bases for …", or name the base
not saved: confirm it first, then run this again with --yes	Claude ran `note` without `--yes`	Say yes to the note it showed; it runs it again with `--yes`
`KNOWLEDGE_BASE_NOT_READY`	The base is not serving yet	Wait for it in Metis → Knowledge bases (Troubleshoot)
`403` on `note`	Your role may search but not add	Ask for `knowledge-bases:write-content`