Show HN: Praana – a terminal coding agent that curates its own context Amit Kumar Dubey released Praana, an open-source terminal coding agent that uses a deterministic compiler to curate context per turn and an optional Cognitive Memory to carry learnings across sessions, aiming to reduce token waste and context drift in long coding sessions. The tool, built with Bun and TypeScript, supports multiple AI providers and is available as a global npm package. 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. Install globally bun add -g praana Or run without installing bunx praana Requires Bun ≥ 1.2 . Install at bun.sh/install https://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 /amitkumardubey/praana/blob/main/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 from active to soft to hard 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 https://amitkumardubey.github.io/praana/ · ARCHITECTURE.md /amitkumardubey/praana/blob/main/docs/ARCHITECTURE.md · concepts.md /amitkumardubey/praana/blob/main/docs/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