contexara 0.3.0

CLI-first memory engine for LLM applications.

Contexara

A CLI-first memory engine for LLM applications. Drop it into any AI system and it remembers what matters — across sessions, without a vector database, without infra.

Install

pip install contexara

Run the setup wizard on first install:

contexara setup

This walks you through AWS credentials and Bedrock model ID, saves them to ~/.contexara/.env, and tests the connection.

How it works

Contexara uses a three-tier memory architecture:

Tier	What	Storage
1 — Raw turns	Every message in the current session	active_state.db → raw_turns
2 — Episodes	LLM-crystallized session summaries	active_state.db → episodes
3 — Semantic facts	Atomic extracted memories	active_state.db → memories

Session lifecycle: Sessions are detected automatically. After 60 minutes of inactivity, the session closes and a background worker crystallizes it into a structured episode (title, actions, outcomes, open items) using the LLM. This never blocks the user.

Context injection: On every ask, all three tiers are injected into the prompt — recent turns for short-term continuity, episode anchor for session handoff, semantic memories for persistent facts.

Temporal queries: Natural language time expressions ("what did I work on today?", "yesterday", "last week") trigger a SQL pre-filter over episodes followed by embedding-based re-ranking.

Cold archive: Raw turns older than 30 days are swept to cold_archive.db automatically every 7 days. The cold archive uses SQLite FTS5 for full-text search across years of history.

Embeddings: Amazon Titan Text Embeddings V2 (1024-dim, serverless via Bedrock) — no local model, no GPU.

Retrieval: Reciprocal Rank Fusion — semantic similarity and keyword overlap ranked independently then fused. Temporal weighting boosts recent task/constraint memories.

Compression: When the store exceeds budget, old memories are compressed by the LLM and originals move to an archive table — permanently recoverable. Every compressed memory carries a compression_level penalty in retrieval.

CLI

contexara ask "what was I working on?"     # memory-aware Q&A
contexara store "prefers Python"           # store a memory
contexara ingest notes.txt                 # bulk ingest .txt / .md / .jsonl
contexara list                             # all memories
contexara list --since 2026-04-01          # filter by date
contexara search "tech stack"             # semantic search
contexara show <id>                        # full detail for one memory
contexara stats                            # counts, sources, age
contexara consolidate                      # LLM-compress all memories
contexara prune                            # archive expired (TTL) memories
contexara prune --dry-run                  # preview without changes
contexara delete <id>                      # delete one memory
contexara chat                             # interactive chat mode

Chat mode

contexara chat

  Contexara Chat  type 'exit' to quit

You: what did I work on yesterday?
──────────────────────────────────────────────
Yesterday you built the cold archive sweep module — moved raw turns
older than 30 days to cold_archive.db with FTS5 full-text indexing.
──────────────────────────────────────────────

Use in code

from contexara import ask, store, retrieve, ingest_turn

store("User prefers concise answers")
ingest_turn(user_text, assistant_text, session_id=session_id)  # auto-extracts + deduplicates
answer = ask("what do I prefer?")
memories = retrieve("python preferences", top_k=5)

Stack

Layer	Technology
Storage	SQLite — raw turns, episodes, memories, cold archive (FTS5)
Embeddings	Amazon Titan Text Embeddings V2 (1024-dim, via Bedrock)
LLM	AWS Bedrock (configurable model) — extraction, crystallization, Q&A
Retrieval	RRF hybrid search + temporal weighting + episode re-ranking
CLI	Python + rich

What's in v0.3.0

• Three-tier memory — raw turns (Tier 1), crystallized episodes (Tier 2), semantic facts (Tier 3)
• JIT session detection — O(1) SQL check, 60-min idle timeout, automatic session lifecycle
• Background crystallization — detached subprocess worker, never blocks user flow
• Temporal retrieval — natural language time queries map to SQL episode pre-filter + cosine re-rank
• Cold archive sweep — FTS5 full-text search across years of history, auto-runs every 7 days
• Setup wizard — guided AWS credential setup with connection test on first install
• Proper system prompt — Bedrock API system field used correctly for instruction/context separation

What's in v0.2.x

• Bedrock embeddings — replaced local BERT (2GB) with Titan V2, no model loading
• File ingest — bulk seed memory from .txt, .md, .jsonl files
• TTL expiry — contexara prune enforces expires_at, auto-sweeps on write
• Date filters — --since / --before on list and search
• Rich terminal UI — colored tables, spinner, progress bar, markdown responses
• Fast-path ingest — low-signal turns skip the LLM entirely
• Temporal weighting — recent tasks rank higher, profiles stay stable

---

Built by Prajwal Narayan