Every conversation starts from zero. Kontext changes that.
Quick Start · How It Works · Commands · Import History · FAQ
You open Claude Code. You explain your project. You describe your preferences. You give context about your situation. Claude gives a great answer.
Next session: Claude has forgotten everything. You start over.
Every. Single. Time.
Kontext stores what Claude needs to know about you in a SQLite database backed by a knowledge graph. Before responding, Claude uses MCP tools to query relevant context and answers as if it's known you for months.
"Your history is my edge. Starve me and I'm generic."
SQLite database as the source of truth. Knowledge graph for entity relations. Semantic search. Score decay for stale entries. Flat markdown files auto-generated for backward compatibility.
git clone https://github.com/numarulunu/kontext.git
cd kontext
./setup.shThen in Claude Code:
/kontext onboard
Answer a few questions. Claude builds your memory library. Done.
flowchart TD
A["You say something\nin Claude Code"] --> B["Claude scans the index\n~2,000 tokens, always loaded"]
B --> C{"Topic match?"}
C -->|Work| D["Loads your\nproject files"]
C -->|Personal| E["Loads your\npreferences + context"]
C -->|Technical| F["Loads your\ntech stack + tools"]
C -->|Just code| G["Skips the library"]
D --> H["Responds with\nfull context"]
E --> H
F --> H
G --> H
style A fill:#1a1a2e,stroke:#e94560,color:#fff
style B fill:#1a1a2e,stroke:#0f3460,color:#fff
style H fill:#1a1a2e,stroke:#22c55e,color:#fff
| Layer | What it does | When it runs |
|---|---|---|
| Real-time | Claude watches every message for facts, decisions, corrections — writes them to memory immediately | Every conversation, always on |
| Daily digest | Script extracts yesterday's conversations, Claude processes them next session | Automated via Task Scheduler / cron |
| Bulk intake | Import your entire ChatGPT, Gemini, or WhatsApp history | On demand |
Nothing falls through the cracks.
Most AI memory systems use vector search — find text that looks similar to your question.
Kontext uses reasoning — it understands why things connect, reads your emotional state, and pulls files you didn't ask for but need.
flowchart LR
subgraph search ["Vector Search (RAG)"]
direction TB
S1["Question"] --> S2["Find similar text"] --> S3["Return matches"]
end
subgraph kontext ["Kontext"]
direction TB
L1["Question"] --> L2["Match topic\n+ read emotion\n+ check cross-refs"] --> L3["Load connected files\nwith reasoning"]
end
style search fill:#2d2d2d,stroke:#666,color:#ccc
style kontext fill:#1a1a2e,stroke:#e94560,color:#fff
| Vector Search (RAG) | Kontext | |
|---|---|---|
| Finds relevant content | By math similarity | By meaning + reasoning |
| Knows why files connect | No | Yes — cross-reference map |
| Detects emotional state | No | Yes — loads different files when stressed vs. building |
| Tracks freshness | No | Yes — timestamps per entry |
| Multi-hop retrieval | No | Yes — file A leads to file B |
| Requires infrastructure | Vector DB + embeddings | SQLite + text files |
| Human-readable | No | Yes — plain markdown |
Kontext creates files based on your life — not a fixed template.
| Example file | What it holds | When Claude reads it |
|---|---|---|
user_profile.md |
Who you are, tools, background | Most conversations |
active_projects.md |
What you're building, statuses | Work discussions |
feedback_rules.md |
How Claude should behave | Tone-sensitive moments |
work_context.md |
Job, team, stack, deadlines | Work problems |
learning.md |
What you're studying, progress | Learning topics |
habits.md |
Routines, patterns, blockers | When you're stuck |
Start with 3 files. Grow to 100. Each one is a page in your library.
More pages = more precision, not more cost.
Every file gets a keyword-rich one-liner in MEMORY.md:
- [Work Context](work.md) — senior dev at Acme, React/Node, deadline March 15, team of 4
- [Side Projects](projects.md) — budgeting app (80% done), blog (stalled), CLI tool
- [How I Work](feedback.md) — short answers, no emojis, explain tradeoffs, push to shipClaude reads this index (~2,000 tokens) every conversation. Matches your topic to the right files instantly.
The index maps connections between files:
work ←→ projects (same stack, competing for time)
habits ←→ goals (procrastination blocks projects)
feedback ←→ work (tone changes when debugging vs. planning)
If Claude loads the work file because you mentioned a deadline, it also checks the habits file — there might be a procrastination pattern that's relevant.
User sounds stressed → load habits + interaction rules
User sounds stuck → load habits + goals
User sounds excited → load projects (ride the momentum)
No keyword matching needed. Claude reads the room.
/kontext onboard Build your library from a conversation
/kontext process-digest Absorb recent conversations into memory
/kontext process-intake Ingest ChatGPT, Gemini, WhatsApp exports
/kontext brainstorm Health check + guided cleanup
/kontext status Quick overview
/kontext resolve Handle contradictions between sources
Or say it naturally — "update my memory", "clean up memory", "how's my library" — Claude invokes the right command.
Running multiple sessions? Kontext keeps them connected.
sequenceDiagram
participant A as Session A
participant M as Memory Files
participant B as Session B
A->>M: Updates project file
A->>M: Writes broadcast
Note over B: You send next message
B->>M: Hook detects broadcast
M->>B: "project file changed"
B->>M: Re-reads updated file
Note over B: Now has fresh context
Changes propagate to all active sessions automatically. No manual refresh.
Years of AI conversations? Kontext ingests them.
# Drop files into intake/
cp conversations.json kontext/intake/chatgpt/
cp gemini-export.txt kontext/intake/gemini/
cp whatsapp-chat.txt kontext/intake/whatsapp/
# Parse and chunk (no AI, runs in seconds)
python pipeline/extract.py
# In Claude Code:
/kontext process-intake| Format | Source | File type |
|---|---|---|
| ChatGPT | Settings > Data Controls > Export | .json or .zip |
| Gemini | Copy-paste conversations | .txt .md |
| Chat > Export | .txt |
|
| Documents | Any text content | .txt .md .pdf |
Not everything is worth remembering. Each chunk gets scored 1-10:
| Grade | Meaning | Destination |
|---|---|---|
| 8-10 | Decisions, facts, preferences | Active memory |
| 5-7 | Useful context, patterns | Historical section |
| 1-4 | Small talk, debugging, noise | Dropped |
Filters ~60-70% of raw data before Claude sees it.
Every entry has an implicit tier:
| Tier | Where | When |
|---|---|---|
| Hot | Active section | Recently written or accessed |
| Warm | Historical section | Valuable but untouched 60+ days |
| Cold | Compressed one-liners | 120+ days, grade 5-6 only |
High-value entries (grade 7+) never compress, regardless of age.
Memory is stored as single facts, not paragraphs:
# Good
- [2026-04] Active students: 24 paying
- [2026-04] Lesson rate: EUR120-150 single (decoy)
- [2026-04] Package: EUR380 / 4 sessions (~EUR95/hr)
# Bad
- User has 24 students, charges EUR120-150 for singles
and EUR380 for packages, uses Stripe and Lunacal,
migrating off PreplyOne fact per line. Faster to scan. Easier to update. More precise to retrieve.
When a fact changes, the old version moves to Historical:
## Active
- [2026-04] Active students: 24 paying
## Historical
- [2026-03] Had 27 active students
- [2025-12] Had 15 active studentsClaude can answer "how has X changed over time?" by reading the trail.
When sources disagree, Kontext logs it and asks you:
CONFLICT: Current tech stack
Version A (ChatGPT 2024): "React 17 + Express"
Version B (Claude 2026): "Migrated to Next.js 15"
Keep A, keep B, merge, or skip?
Your decisions train a pattern library. After 3+ consistent decisions in the same category, Kontext auto-resolves similar conflicts.
flowchart TD
A["You work with Claude"] --> B["Claude detects new info"]
B --> C["Writes to memory\n(atomic fact + date tag)"]
C --> D["Broadcasts to\nother sessions"]
D --> E["Next conversation"]
E --> F["Loads updated memory"]
F --> G["Better context\n= better output"]
G --> A
H["Daily digest\nextracts conversations"] --> C
I["Bulk intake\nfrom ChatGPT/Gemini"] --> C
style A fill:#1a1a2e,stroke:#e94560,color:#fff
style G fill:#1a1a2e,stroke:#22c55e,color:#fff
Kontext includes a local MCP server that finds the right memory files by meaning, not just keywords.
Say "everything feels heavy and I can't start anything" — Kontext matches it to your psychology file, your blind spots, and your goals. No keyword overlap needed. It understands what you mean.
Runs locally on your machine. No cloud. No API calls. Embeddings are cached — re-indexes only when descriptions change.
kontext/
setup.sh One-command installer
install_hooks.py Cross-session sync setup
mcp_server.py MCP server — semantic search + database tools
db.py SQLite database — CRUD, graph, sessions, decay
migrate.py Import flat memory files into database
export.py Export database to backward-compatible markdown
graph.py Knowledge graph — entity extraction and relations
sync.py Startup sync — imports file edits that missed DB
kontext.db SQLite database (auto-created on first use)
SKILL.md /kontext skill for Claude Code
templates/ Starter files for new users
pipeline/ Intake processing engine
tests/ 94 tests, all passing
| Tool | What it adds |
|---|---|
| Claude Backup System | Daily conversation digests that feed Kontext |
| pocketDEV | Weekly project health checks |
Does this work with Claude.ai (browser)?
No. Claude.ai loads all context every turn — no selective retrieval. Kontext requires Claude Code CLI.
How much does memory cost in tokens?
The index costs ~2,000 tokens per turn. Each loaded file costs ~500-1,500 tokens. Compare to stuffing everything into CLAUDE.md: that costs the full file size every single turn. Kontext is 80-95% cheaper.
Can I have too many files?
The index caps at ~200 lines. In practice, 20-100 files covers most use cases. More files = more precision, not more cost. Claude loads 4-6 per conversation.
Does Claude update memory automatically?
Yes — it watches every message for new info and writes immediately. A daily digest catches anything missed. Bulk intake lets you import your entire history from any platform.
Can I read and edit my memory files?
Yes. Plain markdown in ~/.claude/projects/*/memory/. Open in any text editor.
Is my data sent anywhere?
No. Everything stays on your machine. The only external connection is if you choose to back up to a private GitHub repo.