PRAANA

bun add -g praana

bunx praana

Why

Long sessions degrade. The prompt fills with stale tool output, the model drifts, and by turn 15 you're repeating the objective you stated at turn 1. Come back the next day and you re-explain your conventions, your decisions, your constraints — everything that was obvious yesterday.

PRAANA addresses both with two systems. The Adaptive Context Engine curates the prompt on every turn rather than waiting for it to break. Cognitive Memory extracts structured learnings at session end and surfaces them at the start of the next session, in the same repo or anywhere.

What's different

	Typical transcript agent	PRAANA
Long sessions	Full history in prompt; context fills up	Engine mode: tiered state, tool-output distillation, session checkpoint every turn
Next session	Starts cold unless you paste notes	Cognitive Memory: ranked digest from past sessions, project + global scopes
Stack	Often Python, daemon, vector DB required	Bun, SQLite only — no Python, no daemon, no Docker
Claims	Often marketed as solved	Known limitations published upfront; no benchmark claims we can't back

How it works

Adaptive Context Engine (default)

Every turn, a deterministic compiler assembles the prompt from five sections, each with its own token budget:

1. System Frame      — identity, tools, working directory
2. Memory Digest     — cross-session learnings, ranked
3. Active State      — current work objects at full detail
4. Peripheral Stubs  — inactive objects, one-line anchors
5. Recent Turns      — last N turns, budget-capped

State objects — tasks, decisions, constraints, notes — demote from active to soft to hard based on idle turns. Two-pass hydration before each turn (substring match + BM25) promotes them back when the current turn references them. Tool output from git, npm, tsc, and ripgrep is distilled at ingestion; full bytes live in a content-addressed artifact store and are retrievable on demand via retrieve_artifact. A session checkpoint — active request, decisions with rationale, constraints, rolling narrative — is reconciled deterministically every turn so turn 30 still knows what you asked at turn 1.

Cognitive Memory (opt-in)

At /exit, a summariser extracts structured learnings from the transcript across six kinds: fact, preference, decision, pattern, mistake, constraint. Stored in local SQLite with vector search via @huggingface/transformers running in-process — no Ollama required, no sidecar. Confidence decays 5%/day. Entries confirmed across two or more sessions promote to Consolidated Memory and decay ten times slower. Project memories stay scoped to the repo; global preferences surface everywhere. The next session starts with a ranked digest already in the prompt.

Quick start

# Install
bun add -g praana         # global install
# or
bunx praana               # no install

# Set any supported provider key
export ANTHROPIC_API_KEY="sk-ant-..."
# or OPENAI_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, ...

# Launch
praana

PRAANA auto-detects your provider from the environment. On first run with no config, an interactive setup wizard runs. To customise: praana init creates praana.config.toml.

Supported providers

Known limitations

Area	Gap
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	Telemetry scorecard is live. The A/B eval harness — engine vs classic on a fixed task suite — doesn't exist yet. We don't claim the engine beats classic until we can measure it.
Engine is experimental	Engine mode is the default, but classic mode remains available by setting [context_engine] enabled = false.
Background Consolidation	Schema exists, not scalable yet. The full learning loop is incomplete.
Embedder setup	Transformers.js model weights download ~80MB on first run, cached in ~/.praana/models/. Keyword-only FTS fallback always works without a download.
Shell sandbox	Off by default. Shell tool runs with your user permissions. Optional allowlist via [shell] in config.

Documentation

Community

• GitHub Discussions — Q&A, ideas, releases
• Good first issues — contributions welcome
• npm

FAQ

What is PRAANA?

A terminal coding agent built on two systems: an Adaptive Context Engine that curates what the model sees on every turn (tiered working memory, tool-output distillation, session checkpoint), and Cognitive Memory that extracts structured learnings when a session ends and surfaces a ranked digest at the start of the next. Runs on Bun. MIT. Local-first.

Which providers does it work with?

Anthropic, OpenAI, DeepSeek, Groq, Google, Mistral, xAI, Fireworks, Together, OpenCode, OpenRouter, and Ollama for fully local use. PRAANA auto-detects your provider API key from the environment.

How is it different from a plain transcript agent?

Most agents append the full transcript until something breaks, then compact. PRAANA curates the prompt on every turn — tiered state objects demote and hydrate based on relevance, tool output is distilled at ingestion and stored in a content-addressed artifact store, and a deterministic checkpoint preserves decisions and intent when turns scroll out. Cognitive Memory carries learnings across sessions in local SQLite. Known limitations are published upfront. There are no benchmark claims we can't back.

Is it free and open source?

Yes. MIT-licensed. Source on GitHub, published on npm. Install with bun add -g praana or bunx praana.

Does my data leave my machine?

No. Cognitive Memory lives in ~/.praana/memory.db. The only network calls go to the LLM provider you choose. With Ollama, nothing leaves your machine at all.

What do I need to run it?

Bun ≥ 1.2 and an API key for any supported provider. Install Bun at bun.sh/install.

Is the context engine proven to be better than classic mode?

Not yet measured. Engine mode is now the default, but this is still an experimental default. The telemetry scorecard gives session-level signals. The A/B eval harness — comparing engine vs classic on a fixed task suite — is next on the roadmap.