Skip to main content
Tell it something today, and a new chat next week still knows it.

​
What You’ll Build

You point cognee at a folder of notes: a journal, an Obsidian vault, any folder of text files. cognee remembers them, then you chat with a companion that answers from those notes. When the chat ends, cognee writes the chat itself into memory, so the next chat knows what you said. cognee’s databases are local files on your machine; the LLM is the one your .env configures. Building the memory takes one cognee.remember call. Each message is answered with one cognee.recall call, and one cognee.improve call saves the chat when it ends. The complete cookbook is examples/cookbooks/self_hosted_companion/.

​
Try It on Sample Data

The sample is three journal entries from the last three weeks. In one, you called your sister Lena: her birthday is on 4 October, and you plan to give her a pottery class voucher. The sample run asks the companion about it. You need only an LLM key.
LLM_API_KEY alone is enough for OpenAI, cognee’s default for both the LLM and the embeddings. Other providers, such as Anthropic, Gemini, Azure OpenAI, AWS Bedrock or a local model through Ollama, need a few more lines in the same .env: LLM Providers and Embedding Providers list them for each provider. Set both, because embeddings you leave at the default still need an OpenAI key.
The question never names Lena, the date or the studio. The companion found all three in a note from three weeks ago. Now tell it something no note contains, then ask about it in a new chat:
These call the chat script alone, because the notes are already remembered. Running the entry script with --sample again would first forget the dataset, chats included.
In the first chat, no note mentions Pepper, so the companion says so. That chat is saved to memory, and the second chat, a new session, answers from it.

​
Run It on Your Data

  • A folder of notes, such as .md or .txt files, at any depth. Every file in it is remembered, so keep only notes there. Pass its path to the entry script.
--check reports what is missing without doing any work. Without --ask, the chat waits for your messages until you type /bye. Running it again adds new notes and skips unchanged ones; add --clear to forget the dataset first and start over from your notes as they are now, which also forgets the earlier chats. Each script also runs alone, for example uv run python examples/cookbooks/self_hosted_companion/scripts/chat.py.

​
How It Works

​
Step 1: Start From an Empty Memory

Source: scripts/clear.py This step forgets what an earlier run remembered, so old copies never mix with new ones. It runs only with --clear, which a sample run turns on by default; --no-clear keeps the dataset.
The sample notes are named after dates relative to today, so each day’s sample differs from yesterday’s. cognee’s part is one call: cognee.forget(dataset="self_hosted_companion"), which deletes the dataset and everything extracted from it. That includes the earlier chats saved into it, so on your own notes use --clear only to start over.

​
Step 2: Remember Your Notes Folder

Source: scripts/ingest_notes.py This step saves your notes so the companion can answer from them. It reads every file in the folder and its subfolders; there is no limit option, so point it at the folder you want the companion to know.
With --sample, args.notes_folder is the sample folder. cognee’s part is one call: cognee.remember with the folder path, into the dataset self_hosted_companion. A dataset is the named memory everything goes into. remember turns each file into a knowledge graph of people, plans and dates. Running it again skips notes it already holds; an edited note is added as a new document.

​
Step 3: Chat With Your Companion

Source: scripts/chat.py This step runs the chat. Type messages, and /bye ends it; with --ask, it answers one message and ends.
Each message is one cognee.recall with HYBRID_COMPLETION, which answers from the matching note passages and the graph around them, and a session_id. A session is short-term memory for one chat, so each answer sees the turns before it. PROMPT keeps the companion warm, brief, and honest when it does not know. When the chat ends, cognee.improve(dataset="self_hosted_companion", session_ids=[session_id]) writes the chat into the graph. improve is what lets the next chat know what you said in this one.

​
Step 4: Browse the Graph

Source: scripts/ui.py This step opens cognee’s UI so you can see what the companion remembers. It runs only when you pass --ui.
The script starts cognee’s API server in the same process, next to the databases the chat already has open, then cognee.start_ui starts the UI. Open http://localhost:3000 to browse the graph built from your notes and chats. The server listens on localhost only. Ctrl+C stops both.

​
Make It Yours

  • Run it fully on your machine. Point the LLM and the embeddings in .env at Ollama, and your notes and chats never leave your computer; the scripts need no change. The README’s Run fully local section has the exact .env. Use the bare LLM_ENDPOINT=http://localhost:11434 (with /v1, calls return 404), and set AUTO_FEEDBACK=false to skip a second LLM call per message that is slow on a local model.
  • Give it a different personality. Edit PROMPT in scripts/chat.py: a coach that asks one follow-up question, or a study partner that quizzes you on your notes.
  • Point it at your team’s wiki. Pass a folder of exported Markdown pages instead of a journal, and you have a companion that answers from your team’s docs and remembers what you asked it.
  • Start each chat with a check-in. Before the chat loop in scripts/chat.py, call reply("What did I say I'd do this week?", session_id) and print the answer, so the companion opens the conversation.

​
Clean Up

To start over completely, also delete sample/ in the cookbook folder.

Sessions

How a session keeps the turns of one chat together.

Improve

How a finished chat becomes long-term memory.

Personalized Email

Build another one: email replies that know your meetings.

Follow-Up Agent

Build another one: next steps from your latest call, posted to Slack.