How to use the Self-hosted notes companion agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to perform a task. This skill is built on the self-hosted companion cookbook in the cognee repository. It loads a notes folder into cognee's memory, stored in local databases, and then answers your messages about those notes.

Every chat is saved to that memory, so a later conversation can build on an earlier one. If you do not supply your own folder, the skill runs on bundled sample notes so you can see how it works first.

Install the skill from the ZIP or the Claude apps

You can install the skill in either of two ways. Download the ZIP from this page and unzip it into ~/.claude/skills/ to make it available to all your projects, or into a project's .claude/skills/ folder to limit it to that project.

Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check what the skill needs before you run it

The skill needs Python with uv installed, a checkout of the cognee repository that contains the self_hosted_companion cookbook, and an LLM_API_KEY environment variable for an LLM provider. The cookbook creates local cognee databases on first use.

The skill's scripts are run from the repository root. Setup details and the full requirements table are in the cookbook's README, which is not included in this skill's download, so check that file in the repository for the exact steps.

• Python with uv installed
• A cognee repository checkout containing examples/cookbooks/self_hosted_companion/
• LLM_API_KEY set for an LLM provider
• Local cognee databases (created by the cookbook)

Trigger the skill with natural requests

You do not need special syntax. Ask in plain language about your own notes, or ask to talk with a companion that remembers past conversations. The skill's description covers requests such as asking questions about your notes or chatting with a companion that remembers earlier chats.

The agent then runs the cookbook's scripts. If you have not named a folder, it uses the sample notes and tells you the answer comes from them.

• "Using my journal folder, what did I write about the move last spring?"
• "Ask my Obsidian vault what open questions I have about the project."
• "Let's continue yesterday's conversation with the companion."
• "Show me how the notes companion works using the sample notes."

Run a first chat and read the answer

The agent checks your setup first. If the check fails, each missing item is printed on a line starting with [setup] MISSING:, and the agent tells you which one to fix. When the check passes, it sends your message with --ask, because it cannot type into the interactive chat.

Once a folder is remembered, later messages use the chat script on its own. The answer is the text after [chat] companion> in the output.

• First run on your folder: pass the folder path with --ask
• Later messages: the chat script alone with --ask
• Each --ask is its own chat session, saved to memory

Safety notes: scripts, network and your private files

This skill runs scripts and uses the network. Answers and ingestion use an LLM API key, so the content of your notes is processed by that external LLM provider. The skill's files do not say otherwise, so treat it as sent to that service.

The skill reads your notes folder and writes only to cognee's memory. It is instructed not to quote your notes beyond what answers your question and not to print your .env file. Every run uses LLM credits, so it runs only when you ask.

Two options can remove data. The --clear flag forgets everything in the self_hosted_companion dataset, including earlier chats, so use it only when you want to start over. The --ui flag keeps running until you press Ctrl+C, so it is for browsing the graph only.

• Notes may be sent to your LLM provider during ingestion and answers
• --clear forgets the whole dataset, including earlier chats
• --ui keeps running until Ctrl+C
• Remove the saved memory with: uv run cognee-cli forget --dataset self_hosted_companion

Tips for better results

Start with the sample notes to confirm the setup works before pointing the skill at your own folder. Keep the folder you name focused, since the answers depend on what has been remembered from it.

If a script fails, the skill exits with a line naming the problem. To look closer, run that script from examples/cookbooks/self_hosted_companion/scripts/ on its own.

• Test with sample notes first
• Name one folder per memory set so answers stay focused
• If a script fails, run it alone from the scripts folder to see the error