Perzistentní paměť Claude Code

Perzistentní paměť je úložiště (harware), jehož obsah přetrvává i po vypnutí systému – na rozdíl od RAM, která vše ztratí.

Stejný princip platí u AI agentů – model sám je bez paměti, ale externí úložiště (soubory, databáze, vektorová DB) mu umožňují pamatovat si kontext, výsledky a preference mezi sezeními. Agent tak navazuje tam, kde skončil, místo aby začínal vždy od nuly.

V Claude Code (CLI) funguje perzistentní paměť jako externí „digitální mozek“, který překonává omezení bezstavovosti samotného modelu. Zatímco standardní model začíná každou konverzaci s čistým štítem, Claude Code využívá kombinaci souborů CLAUDE.md a automatizovaného systému MEMORY.md k ukládání kontextu, naučených vzorců a architektonických rozhodnutí přímo v adresáři projektu. Díky tomu agent při každém novém spuštění okamžitě ví, jaké jsou vaše kódovací standardy a v jaké fázi vývoje se nacházíte, aniž byste mu to museli znovu vysvětlovat.

Perzistentní paměť u AI agentů

Perzitentní paměť není jedna monolitická schránka, ale vrstvený systém, který se technicky dělí podle toho, jakým způsobem a k čemu data ukládá. Podle analýzy Medium (Nimeth, 2024) je cílem moderní architektury vytvořit adaptivní systémy, které umožňují agentům dlouhodobý vývoj. Tato architektura se opírá o tři hlavní pilíře:

Sémantická paměť (Vektorová)

Ukládá fakta a znalosti ve formě tzv. embeddingů (číselných vektorů) ve vektorových databázích (např. Pinecone, Milvus nebo pgvector v PostgreSQL).

Když se agenta na něco zeptáte, systém nehledá přesná slova, ale „blízké významy“ skrze sémantickou podobnost.

Epizodická paměť (Chronologická)

Uchovává historii konkrétních interakcí a událostí, aby agent věděl, co se stalo „minule“. Rozlišuje epizodickou paměť jako záznam specifických zkušeností. Jde o přesné záznamy chatů, provedené akce agenta a jejich výsledky. Umožňuje agentovi nezacyklit se a učit se z předchozích chyb.

Procedurální a stavová paměť

Ukládá naučené postupy a aktuální nastavení uživatele. Zatímco sémantická paměť řeší „co“ (fakta) a epizodická „kdy“ (historie), tato složka se soustředí na „jak“ a „v jakém stavu“ se proces právě nachází.

Jak to funguje dohromady?

Orchestrátor funguje v celém systému jako „mozek“ nebo „dirigent“. Zatímco jednotlivé typy paměti jsou jako archivy a šanony s informacemi, orchestrátor je ten, kdo ví, kdy do kterého šanonu sáhnout, co z něj vytáhnout a jak to použít k vyřešení úkolu. Právě tato schopnost koordinace činí AI agenty tak výkonnými. Zde je srozumitelný rozpis jeho klíčových funkcí v tomto procesu:

⬇ 1. Řízení toku (Logika procesu)

Orchestrátor rozhoduje o tom, jaká akce bude následovat. Když mu položíte otázku, nezačne hned generovat náhodná slova, ale spustí naprogramovaný řetězec kroků (workflow):

Analýza vstupu: Co po mně uživatel chce?
Volání paměti: Jaké informace k tomu potřebuji dohledat?

⬇ 2. Proces „Vybavení“ (Retrieval) – Příprava scény

Předtím, než orchestrátor osloví samotný jazykový model (LLM), musí mu připravit podklady. Tento proces je základem techniky RAG (Retrieval-Augmented Generation). Funguje to jako rešeršní práce:

Sémantické hledání: Orchestrátor vezme váš dotaz, vytvoří z něj embedding (číselný vektor) a „prožene“ ho vektorovou databází. Najde relevantní fakta (Sémantická paměť).
Kontextualizace: Podívá se do historie chatu, aby věděl, na co navazujete (Epizodická paměť).
Pravidla hry: Přidá aktuální instrukce a stav úkolu (Procedurální paměť).

Všechny tyto kousky orchestrátor „přibalí“ k vašemu původnímu dotazu a pošle je do dočasného kontextového okna (pracovní paměti) modelu. Tento princip sekvenčního zpracování zajistí, že model neodpovídá „z hlavy“, ale na základě konkrétních dat.

⬇ 3. Proces „Uložení“ (Storage) – Učení se za pochodu

Jakmile interakce proběhne, orchestrátor se postará o to, aby se na ni nezapomnělo:

Embedding nové informace: Vezme nově získaný poznatek nebo výsledek úkolu a nechá jej převést na vektor.
Kategorizace: Rozhodne, kam informace patří. Je to fakt? Putuje do sémantické databáze. Je to záznam o tom, co jsme právě udělali? Zapíše se do epizodického deníku.
Aktualizace stavu: Pokud jste právě dokončili krok 2 z pěti, orchestrátor v procedural paměti přepne stav na „krok 3″.

Shrnutí v metafoře

Představte si orchestrátor jako zručného asistenta v kanceláři:

Vybavení: Než jde k šéfovi (LLM) na poradu, skočí do archivu (Vektorová databáze), vytáhne složku s historií klienta (Epizodická paměť) a zkontroluje aktuální manuál firmy (Procedurální paměť). Vše mu to položí na stůl.
Uložení: Po poradě vezme poznámky, které si šéf udělal, nechá je přepsat do čistopisu a pečlivě je založí zpět do archivu, aby byly připravené pro příště.

Frameworky jako LangChain nebo LangGraph tento proces automatizují, takže vývojář nemusí ručně psát kód pro každý přesun dat mezi pamětí a modelem. Pro konfiguraci vlastních AI asistentů s podobnou architekturou můžete využít i protokol MCP (Model Context Protocol).

Co tvoří perzistentní paměť Claude Code?

Perzistentní paměť v Claude Code je schopnost uchovávat informace, kontext projektu, konvence kódování a získané znalosti napříč různými konverzačními relacemi (sessions).

Bez perzistentní paměti začíná v chatu Claude každou novou relaci „s čistým štítem“. To v praxi znamená, že byste museli opakovaně vysvětlovat architekturu projektu, používané technologie nebo vaše preference při kódování. Perzistentní paměť tento problém řeší a umožňuje Claudovi pracovat efektivně od první chvíle nové session.

Dva typy paměti: Automatická vs. manuální

Podle oficiální dokumentace Claude Code existují dva hlavní druhy perzistentní paměti:

1. Auto memory (automatická paměť)

Auto memory je funkce, která Claudovi umožňuje samostatně zapisovat a číst poznatky o vašem projektu. Na rozdíl od manuálních instrukcí se jedná o poznámky, které si Claude píše sám na základě toho, co během práce objeví.

Co si Claude automaticky zapamatuje:

Vzory v projektu — build příkazy, testovací konvence, preferovaný styl kódu
Ladící poznatky — řešení záludných problémů, časté příčiny chyb
Architektonické poznámky — klíčové soubory, vztahy mezi moduly, důležité abstrakce
Vaše preference — komunikační styl, pracovní návyky, volba nástrojů

Kde se auto memory ukládá:

Každý projekt má vlastní adresář paměti v umístění ~/.claude/projects/<project>/memory/. Cesta <project> se odvozuje z kořenového adresáře git repozitáře, takže všechny podadresáře v rámci stejného repo sdílejí jeden adresář auto memory.

Struktura adresáře vypadá takto:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Stručný index, načítá se při každé session
├── debugging.md       # Podrobné poznámky o ladění
├── api-conventions.md # Rozhodnutí o designu API
└── ...                # Další tematické soubory

Soubor MEMORY.md funguje jako rozcestník celého adresáře paměti. Při spuštění nové session se automaticky načte prvních 200 řádků tohoto souboru do systémového promptu. Obsah nad 200 řádků se nenačítá automaticky — Claude je instruován, aby udržoval hlavní soubor stručný a podrobnosti přesouvat do samostatných tematických souborů.

2. Soubory CLAUDE.md (manuální paměť)

Soubory CLAUDE.md slouží jako statické instrukce, které píšete vy — vývojář. Zde definujete standardy kódování, preferované technologie, build příkazy nebo architektonická rozhodnutí.

Claude Code nabízí hierarchickou strukturu paměťových souborů:

Typ paměti	Umístění	Účel	Sdíleno s
Projektová paměť	`./CLAUDE.md` nebo `./.claude/CLAUDE.md`	Instrukce sdílené v týmu	Tým přes git
Projektová pravidla	`./.claude/rules/*.md`	Modulární instrukce podle tématu	Tým přes git
Uživatelská paměť	`~/.claude/CLAUDE.md`	Osobní preference pro všechny projekty	Jen vy
Lokální projektová	`./CLAUDE.local.md`	Vaše soukromá nastavení pro projekt	Jen vy
Auto memory	`~/.claude/projects/<project>/memory/`	Automatické poznámky Clauda	Jen vy

Důležité: Soubory CLAUDE.local.md se automaticky přidávají do .gitignore, což z nich dělá ideální místo pro soukromá nastavení, která nechcete verzovat v repozitáři.

Proč je perzistentní paměť důležitá?

Standardní jazykové modely (LLM) jsou bezstavové — každá nová konverzace začíná s čistým štítem. Perzistentní paměť v Claude Code přináší zásadní výhody:

Úspora tokenů — nemusíte znovu nahrávat dokumentaci nebo vysvětlovat kontext, což šetří jak čas, tak náklady na API volání
Kontinuita práce — i po restartu terminálu nebo počítače Claude ví, na čem jste pracovali
Znalostní báze — agent si buduje dlouhodobou paměť podobnou vektorové databázi o chybách, které opravil, a o konvencích specifických pro projekt
Týmová spolupráce — sdílené CLAUDE.md soubory zajistí, že celý tým dodržuje stejné standardy
Pokročilé workflow — v kombinaci s funkcí compaction nebo context editing lze vést i velmi dlouhé agentic workflow, které by jinak překročily limity kontextového okna

Praktický příklad:

Krok 1: Inicializujte CLAUDE.md pro váš projekt

Nejrychlejší způsob, jak vytvořit projektovou paměť, je použít příkaz /init přímo v Claude Code:

> /init

Claude projde váš projekt a vytvoří soubor CLAUDE.md s relevantními informacemi o architektuře, závislostech a build příkazech.

Krok 2: Přizpůsobte CLAUDE.md svým potřebám

Po inicializaci upravte soubor podle svých specifických požadavků. Příklad obsahu pro český e-commerce projekt:

# Projektová konfigurace

## Technologie
- Framework: Next.js 14 s App Router
- Jazyk: TypeScript (strict mode)
- Databáze: PostgreSQL s Prisma ORM
- Styling: Tailwind CSS

## Build příkazy
- Vývoj: pnpm dev
- Build: pnpm build
- Testy: pnpm test
- Lint: pnpm lint

## Konvence kódování
- Názvy komponent v PascalCase
- Proměnné a funkce v camelCase
- Databázové sloupce ve snake_case
- Komentáře v češtině, kód v angličtině

## Architektura
- /src/app — stránky a routing
- /src/components — znovupoužitelné komponenty
- /src/lib — sdílené utility a helpery
- /src/server — serverová logika a API

Krok 3: Nastavte modulární pravidla

Pro větší projekty můžete organizovat instrukce do modulárních pravidel v adresáři .claude/rules/:

vas-projekt/
├── .claude/
│   ├── CLAUDE.md           # Hlavní projektové instrukce
│   └── rules/
│       ├── code-style.md   # Styl kódu
│       ├── testing.md      # Testovací konvence
│       └── security.md     # Bezpečnostní pravidla

Pravidla mohou být podmíněná — aplikují se jen pro určité soubory pomocí YAML frontmatter:

---
paths:
  - "src/api/**/*.ts"
---

# Pravidla pro API

- Všechny API endpointy musí mít validaci vstupů
- Používej standardní formát chybových odpovědí
- Vždy přidej OpenAPI dokumentační komentáře

Krok 4: Aktivujte auto memory

Auto memory se postupně rozšiřuje ke všem uživatelům. Pokud ji zatím nevidíte, můžete ji vynutit nastavením proměnné prostředí:

# Vynutit zapnutí auto memory
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0

# Vynutit vypnutí auto memory
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Název proměnné používá dvojitou negaci: DISABLE=0 znamená „nevypínej“ a vynutí zapnutí auto memory.

Krok 5: Řekněte Claudovi, co si má zapamatovat

Během práce můžete Claudovi přímo říct, aby si něco uložil do paměti:

> "Zapamatuj si, že používáme pnpm, ne npm"

> "Ulož do paměti, že API testy vyžadují lokální Redis instanci"

> "Zapamatuj si, že komponenty v /src/ui jsou sdílené napříč projekty"

Pro ruční úpravu paměťových souborů použijte příkaz /memory, který otevře výběr souborů ve vašem systémovém editoru.

Jak fungují volání nástrojů pro paměť v API

Pokud vytváříte vlastního AI agenta pomocí Anthropic API, můžete využít Memory Tool — nástroj na straně klienta, který Claudovi umožňuje ukládat a načítat informace přes souborový systém.

Scénář: Představte si, že vyvíjíte chatbota pro českou e-shop podporu. Claude obdrží dotaz zákazníka a nejdříve zkontroluje svou paměť.

1. Zákazník se ptá:

"Potřebuji vrátit zboží, jak mám postupovat?"

2. Claude nejdříve nahlédne do paměti:

{
  "type": "tool_use",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}

3. Systém vrátí obsah adresáře:

/memories
├── reklamacni_rad.xml      (2.1K)
├── obchodni_podminky.xml   (3.5K)
└── caste_dotazy.xml        (1.8K)

4. Claude si přečte relevantní soubor:

{
  "type": "tool_use",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories/reklamacni_rad.xml"
  }
}

5. Na základě uložených informací Claude poskytne přesnou odpověď včetně konkrétních kroků pro vrácení zboží, lhůt a kontaktních údajů — aniž by tyto informace musel mít v kontextovém okně.

Memory Tool je momentálně v beta verzi a vyžaduje hlavičku context-management-2025-06-27 v API požadavcích. Podporované modely zahrnují Claude Opus 4, Sonnet 4 a Haiku 4.5.

Importy v CLAUDE.md

Soubory CLAUDE.md podporují importy dalších souborů pomocí syntaxe @cesta/k/souboru:

Viz @README pro přehled projektu a @package.json pro dostupné npm příkazy.

# Další instrukce
- Git workflow @docs/git-instructions.md

Cesty mohou být relativní i absolutní. Relativní cesty se vyhodnocují vůči souboru obsahujícímu import. Importy mohou být i rekurzivní — až do hloubky 5 úrovní.

Postupy pro práci s pamětí

Na základě doporučení v dokumentaci i praktických zkušeností doporučujeme:

Buďte konkrétní — instrukce „Používej 2mezerové odsazení“ je lepší než „Formátuj kód správně“. Tento princip vychází z prompt engineeringu
Používejte strukturu — formátujte jednotlivé paměťové záznamy jako odrážky a seskupujte je pod popisné nadpisy
Pravidelně revidujte — s vývojem projektu aktualizujte paměťové soubory, aby Claude pracoval vždy s aktuálními informacemi
Udržujte MEMORY.md stručný — podrobnosti přesouvejte do samostatných tematických souborů, protože se načítá jen prvních 200 řádků
Využívejte CLAUDE.local.md — pro soukromá nastavení, která nechcete sdílet přes git (automaticky se přidává do .gitignore)
Organizujte pravidla modulárně — pro větší projekty využijte adresář .claude/rules/ s tematickými soubory

Bezpečnostní aspekty Memory Tool v API

Pokud implementujete Memory Tool ve vlastní aplikaci, Anthropic doporučuje věnovat pozornost několika bezpečnostním oblastem. Podobné principy platí i pro AI agenty využívající techniku RAG (Retrieval-Augmented Generation):

Ochrana citlivých dat — Claude obvykle odmítne zapisovat citlivé informace do paměti, ale implementujte vlastní validaci
Velikost úložiště — sledujte velikost paměťových souborů a zabraňte nekontrolovanému růstu
Expirace paměti — zvažte pravidelné čištění souborů, ke kterým se dlouho nepřistupovalo
Ochrana před path traversal — validujte všechny cesty, aby nemohly přistupovat k souborům mimo adresář /memories

Pro pokročilé implementace s vlastním orchestrátorem a propojením více nástrojů doporučujeme prostudovat protokol MCP (Model Context Protocol).

Závěr

Perzistentní paměť v Claude Code transformuje AI asistenta z bezstavového nástroje na skutečného projektového partnera, který si pamatuje vaše preference, učí se z předchozích sessions a sdílí znalosti v rámci týmu. Kombinace automatické paměti a manuálních CLAUDE.md souborů vám dává plnou kontrolu nad tím, co si Claude zapamatuje a jak s těmito informacemi pracuje.