contexara 0.2.1__tar.gz

contexara-0.2.1/PKG-INFO

@@ -0,0 +1,68 @@
+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)

contexara-0.2.1/README.md

@@ -0,0 +1,50 @@
+# 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)

contexara-0.2.1/contexara/__init__.py

@@ -0,0 +1,11 @@
+"""Contexara public package API."""
+
+from .enhance import enhance
+from .ingest import ingest_turn
+from .main import ask
+from .retrieve import retrieve
+from .store import clear_all, compress_old_memories, consolidate, delete_memory, get_stats, list_all, search_memories, store
+
+__all__ = ["ask", "store", "list_all", "clear_all", "delete_memory", "search_memories", "get_stats", "consolidate", "compress_old_memories", "retrieve", "enhance", "ingest_turn"]
+
+__version__ = "0.2.1"

contexara-0.2.1/contexara/__main__.py

@@ -0,0 +1,7 @@
+"""Module entrypoint for `python -m contexara`."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

contexara-0.2.1/contexara/cli.py

@@ -0,0 +1,236 @@
+"""Command-line interface for Contexara."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Iterable
+
+from . import __version__
+from .main import ask
+from .store import clear_all, consolidate, delete_memory, get_stats, list_all, search_memories, store
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="contexara",
+        description="CLI-first memory engine for LLM context management.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    subparsers.add_parser("chat", help="Start interactive chat mode.").set_defaults(func=_cmd_chat)
+
+    ask_parser = subparsers.add_parser("ask", help="Ask a memory-aware question.")
+    ask_parser.add_argument("query", nargs="+")
+    ask_parser.set_defaults(func=_cmd_ask)
+
+    store_parser = subparsers.add_parser("store", help="Store a memory string.")
+    store_parser.add_argument("content", nargs="+")
+    store_parser.set_defaults(func=_cmd_store)
+
+    subparsers.add_parser("list", help="List all stored memories.").set_defaults(func=_cmd_list)
+
+    delete_parser = subparsers.add_parser("delete", help="Delete a memory by ID.")
+    delete_parser.add_argument("id", type=int, help="Memory ID (from contexara list).")
+    delete_parser.set_defaults(func=_cmd_delete)
+
+    search_parser = subparsers.add_parser("search", help="Semantic search over memories.")
+    search_parser.add_argument("query", nargs="+")
+    search_parser.add_argument("--top", type=int, default=5, help="Number of results (default 5).")
+    search_parser.set_defaults(func=_cmd_search)
+
+    subparsers.add_parser("stats", help="Show memory statistics.").set_defaults(func=_cmd_stats)
+
+    subparsers.add_parser("consolidate", help="LLM-merge overlapping memories.").set_defaults(func=_cmd_consolidate)
+
+    clear_parser = subparsers.add_parser("clear", help="Delete all stored memories.")
+    clear_parser.add_argument("--yes", action="store_true", help="Skip confirmation.")
+    clear_parser.set_defaults(func=_cmd_clear)
+
+    return parser
+
+
+def _join_parts(parts: Iterable[str]) -> str:
+    return " ".join(parts).strip()
+
+
+def _print_memories_table(memories: list[dict]) -> None:
+    if not memories:
+        print("(no memories)")
+        return
+
+    id_w = max(len("ID"), max(len(str(m["id"])) for m in memories))
+    kind_w = max(len("KIND"), max(len(str(m.get("kind", ""))) for m in memories))
+    imp_w = max(len("IMP"), max(len(str(m.get("importance", ""))) for m in memories))
+    src_w = max(len("SRC"), max(len(str(m.get("source", "raw"))) for m in memories))
+    content_w = 60
+
+    header = f"{'ID':<{id_w}}  {'KIND':<{kind_w}}  {'IMP':<{imp_w}}  {'SRC':<{src_w}}  {'CONTENT':<{content_w}}"
+    print(header)
+    print("-" * len(header))
+    for m in memories:
+        content = m["content"]
+        if len(content) > content_w:
+            content = content[: content_w - 3] + "..."
+        print(f"{str(m['id']):<{id_w}}  {str(m.get('kind','')):<{kind_w}}  {str(m.get('importance','')):<{imp_w}}  {str(m.get('source','raw')):<{src_w}}  {content}")
+
+
+def _cmd_chat(_args: argparse.Namespace) -> int:
+    print("\nContexara Chat (type 'exit' to quit)")
+    print("Commands: /store <text>, /list, /show <id>, /delete <id>, /search <query>, /stats, /consolidate, /clear\n")
+
+    while True:
+        user_input = input("You: ").strip()
+        if not user_input:
+            continue
+
+        if user_input.lower() == "exit":
+            print("Goodbye.")
+            return 0
+
+        if user_input.startswith("/store "):
+            store(user_input[7:].strip())
+            print("Memory stored.")
+            continue
+
+        if user_input == "/list":
+            _print_memories_table(list_all())
+            continue
+
+        if user_input.startswith("/delete "):
+            try:
+                mid = int(user_input[8:].strip())
+                if delete_memory(mid):
+                    print(f"Memory {mid} deleted.")
+                else:
+                    print(f"No memory with ID {mid}.")
+            except ValueError:
+                print("Usage: /delete <id>")
+            continue
+
+        if user_input.startswith("/search "):
+            query = user_input[8:].strip()
+            results = search_memories(query)
+            _print_memories_table(results)
+            continue
+
+        if user_input.startswith("/show "):
+            try:
+                mid = int(user_input[6:].strip())
+                match = next((m for m in list_all() if m["id"] == mid), None)
+                if match:
+                    print(f"\nID        : {match['id']}")
+                    print(f"Kind      : {match['kind']}")
+                    print(f"Importance: {match['importance']}")
+                    print(f"Source    : {match.get('source', 'raw')}")
+                    print(f"Level     : {match.get('compression_level', 0)}")
+                    print(f"Created   : {match['created_at']}")
+                    print(f"Content   : {match['content']}\n")
+                else:
+                    print(f"No memory with ID {mid}.")
+            except ValueError:
+                print("Usage: /show <id>")
+            continue
+
+        if user_input == "/consolidate":
+            print("Consolidating memories...")
+            result = consolidate()
+            print(f"Done. {result['before']} memories → {result['after']} memories.")
+            continue
+
+        if user_input == "/stats":
+            _print_stats(get_stats())
+            continue
+
+        if user_input == "/clear":
+            clear_all()
+            print("All memories cleared.")
+            continue
+
+        response = ask(user_input)
+        print(f"\nBot: {response}\n")
+
+    return 0
+
+
+def _print_stats(stats: dict) -> None:
+    print(f"\nTotal memories : {stats['total']}")
+    print(f"Oldest         : {stats['oldest'] or 'N/A'}")
+    print(f"Newest         : {stats['newest'] or 'N/A'}")
+    print("\nBy kind:")
+    for kind, count in stats["by_kind"].items():
+        print(f"  {kind:<12} {count}")
+    print("\nBy source:")
+    for source, count in stats.get("by_source", {}).items():
+        ss = stats.get("source_stats", {}).get(source, {})
+        avg_imp = ss.get("avg_importance", "")
+        avg_age = ss.get("avg_age_days", "")
+        print(f"  {source:<12} {count:<6} avg_importance={avg_imp}  avg_age={avg_age}d")
+    print()
+
+
+def _cmd_ask(args: argparse.Namespace) -> int:
+    print(ask(_join_parts(args.query)))
+    return 0
+
+
+def _cmd_store(args: argparse.Namespace) -> int:
+    store(_join_parts(args.content))
+    print("Memory stored.")
+    return 0
+
+
+def _cmd_list(_args: argparse.Namespace) -> int:
+    _print_memories_table(list_all())
+    return 0
+
+
+def _cmd_delete(args: argparse.Namespace) -> int:
+    if delete_memory(args.id):
+        print(f"Memory {args.id} deleted.")
+    else:
+        print(f"No memory with ID {args.id}.")
+    return 0
+
+
+def _cmd_search(args: argparse.Namespace) -> int:
+    results = search_memories(_join_parts(args.query), top_k=args.top)
+    _print_memories_table(results)
+    return 0
+
+
+def _cmd_stats(_args: argparse.Namespace) -> int:
+    _print_stats(get_stats())
+    return 0
+
+
+def _cmd_consolidate(_args: argparse.Namespace) -> int:
+    print("Consolidating memories...")
+    result = consolidate()
+    print(f"Done. {result['before']} memories → {result['after']} memories.")
+    return 0
+
+
+def _cmd_clear(args: argparse.Namespace) -> int:
+    if not args.yes:
+        confirm = input("Delete all memories? [y/N]: ").strip().lower()
+        if confirm not in {"y", "yes"}:
+            print("Cancelled.")
+            return 0
+    clear_all()
+    print("All memories cleared.")
+    return 0
+
+
+def main() -> int:
+    parser = _build_parser()
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        return 0
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

contexara-0.2.1/contexara/embedder.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import io
+from functools import lru_cache
+
+import numpy as np
+
+_MODEL_NAME = "all-MiniLM-L6-v2"
+
+
+@lru_cache(maxsize=1)
+def _get_model():
+    import logging
+    from sentence_transformers import SentenceTransformer
+    logging.getLogger("transformers.modeling_utils").setLevel(logging.ERROR)
+    return SentenceTransformer(_MODEL_NAME)
+
+
+def embed(text: str) -> np.ndarray:
+    """Return a normalized float32 embedding vector for text."""
+    model = _get_model()
+    vector = model.encode(text, normalize_embeddings=True)
+    return vector.astype(np.float32)
+
+
+def serialize(vector: np.ndarray) -> bytes:
+    buf = io.BytesIO()
+    np.save(buf, vector)
+    return buf.getvalue()
+
+
+def deserialize(blob: bytes) -> np.ndarray:
+    buf = io.BytesIO(blob)
+    return np.load(buf)
+
+
+def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
+    """Cosine similarity for pre-normalized vectors (dot product suffices)."""
+    return float(np.dot(a, b))

contexara-0.2.1/contexara/enhance.py

@@ -0,0 +1,30 @@
+def enhance(query: str, memories: list[str]) -> str:
+    """
+    Build an enhanced prompt by injecting relevant memories.
+    """
+
+    if not query or not query.strip():
+        raise ValueError("Query cannot be empty")
+
+    query = query.strip()
+
+    # Format memory block
+    if memories:
+        memory_lines = "\n".join(f"- {m}" for m in memories)
+
+        context_block = f"""You are an AI assistant with memory.
+
+Relevant context:
+{memory_lines}
+
+"""
+    else:
+        context_block = "You are an AI assistant.\n\n"
+
+    # Final prompt
+    prompt = f"""{context_block}User:
+{query}
+
+Assistant:"""
+
+    return prompt