A terminal coding agent that manages context like memory — curating what the model sees on every turn, and carrying learnings across sessions in a local database.
Long coding sessions burn tokens faster as they grow. The prompt fills with stale tool output and repeated context, the model drifts, and you lose the thread. Come back the next day and you re-explain everything from scratch.
PRAANA takes a different approach. A deterministic compiler curates what the model sees on every turn — tiered working memory, tool-output distillation, and a session checkpoint — instead of stuffing the full transcript into the prompt. An optional Cognitive Memory extracts learnings when a session ends and surfaces a ranked digest the next time you start, in the same repo or anywhere.
Runs on Bun. One binary, pure TypeScript, local-first, any provider.
Status:v0.10.0 — experimental. The context engine and memory are ideas we're proving in real use, not solved problems. We publish[known limitations]and make no benchmark claims we can't back.
How it was built:vibecoded — written by coding agents with human direction and review, not hand-coded line by line.
bun add -g praana
bunx praana
Requires Bun ≥ 1.2. Install at bun.sh/install.
export ANTHROPIC_API_KEY="sk-ant-..." # or any supported provider below
praana
PRAANA auto-detects which provider key is set. On first run with no config file, it runs an interactive setup wizard. The interactive UI is a terminal-native pi-tui
shell with native scrollback, slash-command autocomplete, transcript rendering, and full thinking-text display when /thinking on
is enabled.
Both praana
and pran
are on your PATH after a global install. If Bun's global bin directory isn't in your PATH:
export PATH="$HOME/.bun/bin:$PATH"
git clone https://github.com/amitkumardubey/praana.git
cd praana
bun install
export ANTHROPIC_API_KEY="sk-ant-..."
bun src/main.ts
No config file is needed to start. To customise:
praana init # Creates praana.config.toml with detected provider
See praana.config.example.toml for all settings.
| Provider | Environment variable |
|---|---|
| Anthropic | ANTHROPIC_API_KEY |
| OpenAI | OPENAI_API_KEY |
| DeepSeek | DEEPSEEK_API_KEY |
| Groq | GROQ_API_KEY |
GOOGLE_GENERATIVE_AI_API_KEY |
|
| Mistral | MISTRAL_API_KEY |
| xAI | XAI_API_KEY |
| Fireworks | FIREWORKS_API_KEY |
| Together | TOGETHER_API_KEY |
| OpenCode | OPENCODE_API_KEY |
| OpenRouter | OPENROUTER_API_KEY |
| Ollama | (local — no key needed) |
Provider resolution order: explicit config → environment-detected key → interactive setup.
| Typical transcript agent | PRAANA | |
|---|---|---|
| Long sessions | ||
| Full history in the prompt; context window fills up | Engine mode: curates the prompt every turn — tiered state, tool-output distillation, session checkpoint | |
| Next session | ||
| Starts cold unless you paste notes | Cognitive Memory: at /exit PRAANA extracts what you decided and learned; start tomorrow and it surfaces without re-explaining |
|
| Skills | ||
| Manual or always-on | Pull model: compact catalog injected every turn (usefulness-ranked); load_skill fetches body on demand; effectiveness scores persist across sessions |
|
| Claims | ||
| Often marketed as solved | Known limitations published upfront; no benchmark claims we can't back |
Example workflow: session 1 — decide "use Vitest, in-memory SQLite in tests"
then /exit
. Session 2, same repo — /digest
surfaces the decision. Engine mode stubs yesterday's task graph instead of replaying every tool result.
Per-turn deterministic compiler with per-section token budgets. The prompt is assembled fresh every turn across five sections — system frame, memory digest, active state, peripheral stubs, recent turns — each with its own cap. Context pressure is density-weighted, not a raw token count. -
Tiered working memory with auto-hydration. State objects (tasks, decisions, constraints, notes) demote fromactive
tosoft
tohard
based on idle turns. Two-pass hydration before each turn — substring keyword match, then BM25 — promotes them back when the current turn references them. -
Tool-output distillers with a content-addressed artifact store. Git diffs, npm test output, TypeScript errors, ripgrep results hit built-in distillers at ingestion. The model sees a focused summary. Full bytes live in an artifact store;retrieve_artifact
fetches them on demand. -
Session resume by O(1) checkpoint + event replay. A deterministic checkpoint is written every turn — active request, rolling narrative, decisions with rationale, constraints. Resume restores the checkpoint and replays only post-checkpoint events. -
Agent-native cross-session memory in local SQLite. At/exit
, PRAANA's summariser extracts learnings from the transcript — not bolted-on notes, not an MCP plugin. Six taxonomy kinds:fact
,preference
,decision
,pattern
,mistake
,constraint
. Semantic search via Transformers.js (in-process, no sidecar). Project and global scopes queried and merged.
Two compile modes (set [context_engine] enabled
in config):
| Mode | Default | Behaviour |
|---|---|---|
| Engine | ||
| Yes | Tiered working memory, tool-output distillation, session checkpoint, scored prompt compilation, progressive skills. | |
| Classic | ||
| Fallback / explicit disable | Full verbatim transcript. Same shape as most coding agents. |
Cognitive Memory (optional — [memory] enabled = true
):
- At
/exit
, extracts facts, decisions, patterns, mistakes, preferences, and constraints from the transcript. - Next session starts with a ranked digest in the prompt.
- Project sessions query both project-scoped and global memories and merge results.
- Confidence decays 5%/day. Entries confirmed across two or more sessions promote to Consolidated Memory (10x slower decay).
Skills: discovers SKILL.md
files in project and user paths. Compact catalog injected every turn, sorted by usefulness score. load_skill(id)
fetches the full body on demand. Engine mode tracks whether each skill was used and updates its score in memory.db
.
Project context: loads AGENTS.md
/ CLAUDE.md
and an optional stack fingerprint on session start.
Architecture details: docs site · ARCHITECTURE.md · concepts.md
These are real gaps, not a roadmap dressed as marketing.
| Area | What's weak |
|---|---|
| Memory reinforcement | |
| Memory stores, recalls, and applies time decay. Confidence boost on session success is wired but dormant until the session-success signal ships (#162). | |
| No published evals | |
| The telemetry scorecard is live. The A/B eval harness — comparing engine vs classic on a fixed task suite — doesn't exist yet. We don't know if engine mode beats classic for your workflows. | |
| Semantic recall | |
@huggingface/transformers weights download on first run (~80MB, cached in ~/.praana/models/ ). Ollama is opt-in. Near-duplicate or conflicting memory entries are not automatically reconciled. |
|
| Context engine | |
On by default. Falls back to classic if initialization fails or if you set [context_engine] enabled = false . |
|
| Background Consolidation Processor | |
| Schema exists, not scalable yet. The learning loop is incomplete. | |
| Intelligent Router | |
| Not started. Planned for after memory is proven. | |
| Shell tool | |
Runs with your user permissions. Optional path/command sandbox via [shell] in config — off by default. |
If Cognitive Memory doesn't help you after a few real projects, tell us. That's useful feedback, not a surprise.
| Command | Purpose |
|---|---|
/help |
|
| Full list | |
/exit |
|
| End session — runs summariser when memory is on | |
/clear |
|
| Reset in-session context (same session ID; clears working memory and model-visible history) | |
/new |
|
| Start a new session (new ID, reload config, background summariser) | |
/state |
|
| Working-memory objects (engine mode) | |
/digest |
|
| Cognitive Memory digest | |
/recall <query> |
|
| Search Cognitive Memory | |
/stats |
|
| Session + memory stats | |
/scorecard |
|
| Per-session telemetry signals | |
/events |
|
| Last 20 session log events | |
/model [provider] <id> |
|
| Switch model or provider mid-session | |
/sessions |
|
| List sessions to resume | |
| `/thinking <on | off>` |
| Show or hide reasoning text | |
| `/incognito <on | off>` |
| Disable Cognitive Memory writes | |
/debug |
|
| Verbose tooling + saved prompts | |
/why <id> |
|
| Why a context unit was included (engine + debug) |
/model # show current provider/model
/model gpt-4o # model on current provider
/model openai gpt-4o # switch to OpenAI native
/model opencode mimo-v2.5-free # switch to OpenCode
/model openrouter openai/gpt-4o # route via OpenRouter
Unknown ids resolve against the bundled pi-ai catalog first, then against the provider's live /models
list (cached 6 hours at ~/.praana/provider-catalog-cache.json
).
bun dev # run without build step
bun typecheck # TypeScript type-check (no emit)
bun test # 997 tests across 83 files, ~11s
GitHub Pages is built from website/. Markdown sources in
docs/
cd website && bun install && bun run dev # http://localhost:4321/praana/
cd website && bun run build # output → website/dist/
See ROADMAP.md. Short version: closing the memory reinforcement loop (#162), building the A/B eval harness (#17), and semantic tier management — the work that turns "stores and recalls" into a system that measurably improves with use.
Contributing: CONTRIBUTING.md · good first issues · Discussions
Issues and PRs welcome.
MIT — LICENSE. Version history: CHANGELOG.md (auto-generated by release-please).