Metadata-Version: 2.4
Name: contexara
Version: 0.2.1
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: sentence-transformers>=3.0.0
Requires-Dist: numpy>=1.26.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
```

## How it works

Every conversation turn is analysed by an LLM (AWS Bedrock Haiku) and distilled into atomic facts. Facts are embedded with `all-MiniLM-L6-v2` and stored as BLOBs in a local SQLite file — no external services required.

Retrieval uses **Reciprocal Rank Fusion**: semantic similarity and keyword overlap are ranked independently then fused, so queries work whether you ask loosely or precisely.

Memories are never deleted. When the store exceeds a budget threshold, old memories are compressed into sharp facts by the LLM and the originals move to an archive table — permanently recoverable. Every compressed memory carries a `compression_level` and is penalised in retrieval accordingly. Raw memories always beat compressed ones when scores are close.

## CLI

```bash
contexara ask "what was I working on?"
contexara store "prefers Python for backend work"
contexara list
contexara search "tech stack"
contexara stats
contexara consolidate
contexara delete <id>
```

## Use in code

```python
from contexara import ask, store, retrieve, ingest_turn

store("User prefers concise answers")
ingest_turn(user_text, assistant_text)   # auto-extracts memories
answer = ask("what do I prefer?")
```

## Stack

- Storage: SQLite (embeddings as BLOBs, archive table included)
- Embeddings: `all-MiniLM-L6-v2` via sentence-transformers
- LLM: AWS Bedrock (Haiku) — extraction, compression, Q&A
- Retrieval: RRF hybrid search + source-aware ranking

---

Built by [Prajwal Narayan](https://github.com/Prajwal-Narayan)
