Metadata-Version: 2.4
Name: contexara
Version: 0.3.0
Summary: CLI-first memory engine for LLM applications.
Author: Contexara Contributors
Project-URL: Homepage, https://github.com/Prajwal-Narayan/Contexara
Project-URL: Repository, https://github.com/Prajwal-Narayan/Contexara
Keywords: llm,memory,agentic-ai,retrieval,context
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.34.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"

# 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

```bash
pip install contexara
```

Run the setup wizard on first install:

```bash
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

```bash
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

```text
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

```python
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](https://github.com/Prajwal-Narayan)
