# Skill: Build and maintain a structured knowledge base so the agent remembers across sessions

> Lets an AI coding agent create and upkeep a file-based knowledge base (facts, decisions, long docs) so it starts every new session informed rather than amnesiac -- applies to any project that spans more than one session.

Source: sodigi·learn -- vibecoding/tvoya-baza-znaniy · https://sodigi.io/learn/vibecoding/tvoya-baza-znaniy

## When to use
- A project spans multiple sessions and the agent must retain context (font choice, client name, architecture decisions).
- The user finds themselves re-explaining the same briefing every session.
- A decision needs to be preserved along with the reason, not just the outcome.
- The user wants to return to a project after a gap without rebuilding context from scratch.

## Core rules
- The agent's memory between runs is **zero**. Any fact that must persist must live in a file -- not in the chat.
- Organize files as shelves, not one big dump: (1) **project-facts** -- quick notes, preferences, key context; (2) **decisions** -- what was decided AND why; (3) long documents -- research, detailed instructions, stored separately with a short summary in the quick notes; (4) semantic search index -- optional advanced layer.
- Start with just two files: `project-facts.md` and `decisions.md`. Add more shelves when a real need appears.
- **Search before writing.** Before adding any fact, check if it already exists. If it does, update the old entry -- do not create a duplicate. Contradictory notes are worse than no notes.
- Keep notes short: one note, one fact, one place.
- File names: lowercase, hyphen-separated, no spaces.
- **Never put secrets** (passwords, API keys, tokens) in knowledge base files. They leak.
- Weed regularly: archive stale entries instead of letting the base grow indefinitely.
- At the start of every new session, the agent reads the knowledge base files before taking on the task.

## Procedure
1. On project setup, create `project-facts.md` and `decisions.md` in the project root (or a `.kb/` folder).
2. In project-facts: record the project name, writing language, deadline, key contacts, and current preferences.
3. In decisions: record every architectural or design choice as `[WHAT was decided] -- [WHY]`.
4. Each time a new fact or decision emerges during a session, classify it (facts vs. decisions), search for duplicates, then write it to the right file in one short entry.
5. At the start of each new session: read both files first, then accept the task.
6. Before finishing a task, run the quick weed checklist: no duplicates, no secrets, no stale contradictions, no unbounded file growth.

## Ready-to-use prompt
```
Set up and maintain a knowledge base for this project:

1. Create project-facts.md and decisions.md.
   Use lowercase, hyphen-separated file names.
2. In project-facts: record the project name, text language, deadline, contacts,
   and current design preferences.
3. In decisions: record each choice as "[WHAT was decided] -- [WHY it was decided]."
4. Before adding any new fact, search the existing files first.
   If the fact already exists, update the old entry instead of creating a second one.
5. Never store passwords, API keys, or tokens in these files.
6. At the start of every new session: read both files first, then start the task.
```

## Pitfalls
- Storing decisions only in the chat -- a new session wipes them completely.
- Only ever adding to the base and never cleaning it -- duplicates and stale entries accumulate until the base hurts more than it helps.
- Not searching before writing -- one fact ends up in five slightly different notes and the agent cannot tell which is current.
- Dumping everything into one giant file -- finding anything in a thousand-line wall is hopeless; split by meaning.
- Recording "what was decided" without "why" -- a month later the decision is mysteriously undone because no one remembered the reason.
- Putting API keys or tokens in knowledge base files "so they won't get lost" -- that is a security hole.