{"slug": "show-hn-praana-a-terminal-coding-agent-that-curates-its-own-context", "title": "Show HN: Praana – a terminal coding agent that curates its own context", "summary": "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.", "body_md": "**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.**\n\nLong 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.\n\nPRAANA 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.\n\nRuns on Bun. One binary, pure TypeScript, local-first, any provider.\n\nStatus: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.\n\nHow it was built:vibecoded — written by coding agents with human direction and review, not hand-coded line by line.\n\n```\n# Install globally\nbun add -g praana\n\n# Or run without installing\nbunx praana\n```\n\nRequires **Bun ≥ 1.2**. Install at [bun.sh/install](https://bun.sh/install).\n\n```\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"    # or any supported provider below\npraana\n```\n\nPRAANA 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`\n\nshell with native scrollback, slash-command autocomplete, transcript rendering, and full thinking-text display when `/thinking on`\n\nis enabled.\n\nBoth `praana`\n\nand `pran`\n\nare on your PATH after a global install. If Bun's global bin directory isn't in your PATH:\n\n```\nexport PATH=\"$HOME/.bun/bin:$PATH\"\ngit clone https://github.com/amitkumardubey/praana.git\ncd praana\nbun install\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\nbun src/main.ts\n```\n\nNo config file is needed to start. To customise:\n\n```\npraana init   # Creates praana.config.toml with detected provider\n```\n\nSee [ praana.config.example.toml](/amitkumardubey/praana/blob/main/praana.config.example.toml) for all settings.\n\n| Provider | Environment variable |\n|---|---|\n| Anthropic | `ANTHROPIC_API_KEY` |\n| OpenAI | `OPENAI_API_KEY` |\n| DeepSeek | `DEEPSEEK_API_KEY` |\n| Groq | `GROQ_API_KEY` |\n`GOOGLE_GENERATIVE_AI_API_KEY` |\n|\n| Mistral | `MISTRAL_API_KEY` |\n| xAI | `XAI_API_KEY` |\n| Fireworks | `FIREWORKS_API_KEY` |\n| Together | `TOGETHER_API_KEY` |\n| OpenCode | `OPENCODE_API_KEY` |\n| OpenRouter | `OPENROUTER_API_KEY` |\n| Ollama | (local — no key needed) |\n\nProvider resolution order: explicit config → environment-detected key → interactive setup.\n\n| Typical transcript agent | PRAANA | |\n|---|---|---|\nLong sessions |\nFull history in the prompt; context window fills up | Engine mode: curates the prompt every turn — tiered state, tool-output distillation, session checkpoint |\nNext session |\nStarts cold unless you paste notes | Cognitive Memory: at `/exit` PRAANA extracts what you decided and learned; start tomorrow and it surfaces without re-explaining |\nSkills |\nManual or always-on | Pull model: compact catalog injected every turn (usefulness-ranked); `load_skill` fetches body on demand; effectiveness scores persist across sessions |\nClaims |\nOften marketed as solved | Known limitations published upfront; no benchmark claims we can't back |\n\n**Example workflow:** session 1 — `decide \"use Vitest, in-memory SQLite in tests\"`\n\nthen `/exit`\n\n. Session 2, same repo — `/digest`\n\nsurfaces the decision. Engine mode stubs yesterday's task graph instead of replaying every tool result.\n\n-\n**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. -\n**Tiered working memory with auto-hydration.** State objects (tasks, decisions, constraints, notes) demote from`active`\n\nto`soft`\n\nto`hard`\n\nbased on idle turns. Two-pass hydration before each turn — substring keyword match, then BM25 — promotes them back when the current turn references them. -\n**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`\n\nfetches them on demand. -\n**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. -\n**Agent-native cross-session memory in local SQLite.** At`/exit`\n\n, PRAANA's summariser extracts learnings from the transcript — not bolted-on notes, not an MCP plugin. Six taxonomy kinds:`fact`\n\n,`preference`\n\n,`decision`\n\n,`pattern`\n\n,`mistake`\n\n,`constraint`\n\n. Semantic search via Transformers.js (in-process, no sidecar). Project and global scopes queried and merged.\n\n**Two compile modes** (set `[context_engine] enabled`\n\nin config):\n\n| Mode | Default | Behaviour |\n|---|---|---|\nEngine |\nYes | Tiered working memory, tool-output distillation, session checkpoint, scored prompt compilation, progressive skills. |\nClassic |\nFallback / explicit disable | Full verbatim transcript. Same shape as most coding agents. |\n\n**Cognitive Memory** (optional — `[memory] enabled = true`\n\n):\n\n- At\n`/exit`\n\n, extracts facts, decisions, patterns, mistakes, preferences, and constraints from the transcript. - Next session starts with a ranked digest in the prompt.\n- Project sessions query both project-scoped and global memories and merge results.\n- Confidence decays 5%/day. Entries confirmed across two or more sessions promote to Consolidated Memory (10x slower decay).\n\n**Skills:** discovers `SKILL.md`\n\nfiles in project and user paths. Compact catalog injected every turn, sorted by usefulness score. `load_skill(id)`\n\nfetches the full body on demand. Engine mode tracks whether each skill was used and updates its score in `memory.db`\n\n.\n\n**Project context:** loads `AGENTS.md`\n\n/ `CLAUDE.md`\n\nand an optional stack fingerprint on session start.\n\nArchitecture 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)\n\nThese are real gaps, not a roadmap dressed as marketing.\n\n| Area | What's weak |\n|---|---|\nMemory reinforcement |\nMemory stores, recalls, and applies time decay. Confidence boost on session success is wired but dormant until the session-success signal ships (#162). |\nNo published evals |\nThe 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. |\nSemantic recall |\n`@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. |\nContext engine |\nOn by default. Falls back to classic if initialization fails or if you set `[context_engine] enabled = false` . |\nBackground Consolidation Processor |\nSchema exists, not scalable yet. The learning loop is incomplete. |\nIntelligent Router |\nNot started. Planned for after memory is proven. |\nShell tool |\nRuns with your user permissions. Optional path/command sandbox via `[shell]` in config — off by default. |\n\nIf Cognitive Memory doesn't help you after a few real projects, tell us. That's useful feedback, not a surprise.\n\n| Command | Purpose |\n|---|---|\n`/help` |\nFull list |\n`/exit` |\nEnd session — runs summariser when memory is on |\n`/clear` |\nReset in-session context (same session ID; clears working memory and model-visible history) |\n`/new` |\nStart a new session (new ID, reload config, background summariser) |\n`/state` |\nWorking-memory objects (engine mode) |\n`/digest` |\nCognitive Memory digest |\n`/recall <query>` |\nSearch Cognitive Memory |\n`/stats` |\nSession + memory stats |\n`/scorecard` |\nPer-session telemetry signals |\n`/events` |\nLast 20 session log events |\n`/model [provider] <id>` |\nSwitch model or provider mid-session |\n`/sessions` |\nList sessions to resume |\n`/thinking <on|off>` |\nShow or hide reasoning text |\n`/incognito <on|off>` |\nDisable Cognitive Memory writes |\n`/debug` |\nVerbose tooling + saved prompts |\n`/why <id>` |\nWhy a context unit was included (engine + debug) |\n\n```\n/model                          # show current provider/model\n/model gpt-4o                   # model on current provider\n/model openai gpt-4o            # switch to OpenAI native\n/model opencode mimo-v2.5-free  # switch to OpenCode\n/model openrouter openai/gpt-4o # route via OpenRouter\n```\n\nUnknown ids resolve against the bundled pi-ai catalog first, then against the provider's live `/models`\n\nlist (cached 6 hours at `~/.praana/provider-catalog-cache.json`\n\n).\n\n```\nbun dev          # run without build step\nbun typecheck    # TypeScript type-check (no emit)\nbun test         # 997 tests across 83 files, ~11s\n```\n\nGitHub Pages is built from [ website/](/amitkumardubey/praana/blob/main/website). Markdown sources in\n\n[are rendered at build time.](/amitkumardubey/praana/blob/main/docs)\n\n`docs/`\n\n```\ncd website && bun install && bun run dev    # http://localhost:4321/praana/\ncd website && bun run build                 # output → website/dist/\n```\n\nSee [ROADMAP.md](/amitkumardubey/praana/blob/main/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.\n\n**Contributing:** [CONTRIBUTING.md](/amitkumardubey/praana/blob/main/CONTRIBUTING.md) · [good first issues](https://github.com/amitkumardubey/praana/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) · [Discussions](https://github.com/amitkumardubey/praana/discussions)\n\nIssues and PRs welcome.\n\nMIT — [LICENSE](/amitkumardubey/praana/blob/main/LICENSE). Version history: [CHANGELOG.md](/amitkumardubey/praana/blob/main/CHANGELOG.md) (auto-generated by release-please).", "url": "https://wpnews.pro/news/show-hn-praana-a-terminal-coding-agent-that-curates-its-own-context", "canonical_source": "https://github.com/amitkumardubey/praana", "published_at": "2026-07-11 19:29:35+00:00", "updated_at": "2026-07-11 20:05:31.812340+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "large-language-models", "ai-tools"], "entities": ["Amit Kumar Dubey", "Praana", "Bun", "Anthropic", "OpenAI", "DeepSeek", "Groq", "Google"], "alternates": {"html": "https://wpnews.pro/news/show-hn-praana-a-terminal-coding-agent-that-curates-its-own-context", "markdown": "https://wpnews.pro/news/show-hn-praana-a-terminal-coding-agent-that-curates-its-own-context.md", "text": "https://wpnews.pro/news/show-hn-praana-a-terminal-coding-agent-that-curates-its-own-context.txt", "jsonld": "https://wpnews.pro/news/show-hn-praana-a-terminal-coding-agent-that-curates-its-own-context.jsonld"}}