Metadata-Version: 2.4
Name: bitacorista
Version: 2.1.0
Summary: Structured memory for AI conversations. Mechanical event detection + semantic search, no LLM required.
Author-email: Fito Prunotto <fito@arcanomedia.com>
License: MIT
Project-URL: Homepage, https://github.com/Fito-panda/bitacorista-py
Project-URL: Repository, https://github.com/Fito-panda/bitacorista-py
Project-URL: Issues, https://github.com/Fito-panda/bitacorista-py/issues
Keywords: ai-memory,conversation-memory,sqlite,llm-tools,claude-code,embeddings,onnx,structured-memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: search
Requires-Dist: sqlite-vec>=0.1.1; extra == "search"
Provides-Extra: embeddings
Requires-Dist: bitacorista[search]; extra == "embeddings"
Requires-Dist: onnxruntime>=1.16.0; extra == "embeddings"
Requires-Dist: tokenizers>=0.15.0; extra == "embeddings"
Provides-Extra: dev
Requires-Dist: bitacorista[embeddings]; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mypy<1.16,>=1.10; extra == "dev"
Provides-Extra: dev-lite
Requires-Dist: bitacorista[search]; extra == "dev-lite"
Requires-Dist: pytest>=7.0; extra == "dev-lite"
Requires-Dist: mypy<1.16,>=1.10; extra == "dev-lite"
Dynamic: license-file

# Bitacorista

[![Tests](https://github.com/Fito-panda/bitacorista-py/actions/workflows/test.yml/badge.svg)](https://github.com/Fito-panda/bitacorista-py/actions/workflows/test.yml)

> Your AI assistant forgets what you decided 20 messages ago. Bitacorista fixes that without calling an LLM.

Long conversations with AI lose context. You say "drop React, go with Vue" on message 12, and by message 50 the assistant suggests React again. Memory systems exist (Mem0, Zep, Letta) — but they all need an LLM to decide what to remember. That's a circular dependency.

**Bitacorista breaks the loop:** regex detects events mechanically, SQLite stores them, embeddings power semantic search. No LLM at runtime. Deterministic. Auditable. Local.

## Install

```bash
pip install bitacorista                # core only — zero dependencies
pip install bitacorista[search]        # + sqlite-vec for vector search
pip install bitacorista[embeddings]    # + search + ONNX runtime for embeddings
```

If using embeddings, download the model (~470MB, one-time):

```bash
python -m bitacorista.download_model
```

## Quick start

### CLI

```bash
bitacorista init
bitacorista process --user "We decided to use Vue. Drop React — too complex."
bitacorista entries
bitacorista resumen          # ~20-line summary for AI context injection
bitacorista buscar "framework"
bitacorista descartes        # discards with WHY, for reevaluation
```

### Python

```python
from bitacorista import init_db, process_exchange, get_resumen

conn = init_db("my-session.db")
entries = process_exchange(conn, "We decided to use Vue. Drop React.")
print(get_resumen(conn))
```

## What it detects

| Type | Example | Spanish | English |
|------|---------|---------|---------|
| Decision | "we decided to use Vue" | "decidimos usar Vue" | "we decided to use Vue" |
| Discard | "drop React" | "descartamos React" | "let's discard React" |
| Correction | "no, that's wrong" | "eso esta mal" | "that's wrong, fix it" |
| Topic change | "switching gears" | "cambiemos de tema" | "let's switch to" |
| Deliverable | "create the config file" | "arma el archivo" | "create the file" |
| Discovery | "turns out it has rate limits" | "resulta que tiene limites" | "I found out that" |
| Hypothesis | "my hypothesis is..." | "mi hipotesis es..." | "my hypothesis is..." |
| Source | "according to the docs..." | "segun la documentacion" | "according to..." |

Bilingual detection (Spanish + English). Last two types available in proyecto mode only.

## Why this is different

| | Bitacorista | Mem0 / Zep / Letta |
|---|---|---|
| **Detection** | Regex (deterministic) | LLM call (probabilistic) |
| **Runtime LLM** | None | Required |
| **Latency** | ~0ms detection | 500ms+ per memory operation |
| **Cost** | $0 | LLM API costs |
| **Discards** | Documented with WHY | Deleted or ignored |
| **Auditability** | Regex patterns, visible | Black box |
| **Storage** | Single SQLite file | External DB + API |
| **Embeddings** | Local ONNX (optional) | Cloud API (required) |

### The key insight

Other systems delete what you discard. Bitacorista documents WHY you discarded it, so you can reevaluate later. Discards are gold — they're anti-confirmation-bias.

## Entry states

| State | Meaning |
|-------|---------|
| **FIRME** | User said it explicitly ("we decided", "confirmed") |
| **INFERIDO** | System detected it, no explicit confirmation |
| **DESCARTADO** | Discarded WITH context (gold for reevaluation) |
| **OBSOLETO** | Replaced by a newer decision |

## Architecture

```
bitacorista/
  db.py       <- SQLite + sqlite-vec. Sole gate to data.
  engine.py   <- Regex detection + embeddings + blast radius.
  cli.py      <- 15 CLI commands.
```

One `.db` file per session. No intermediate files. No Markdown as source of truth.

### How it works

1. **Regex detection** scans user messages for event patterns (8-10 types, bilingual)
2. **State classification** determines FIRME/INFERIDO/DESCARTADO based on explicit signals
3. **Embedding generation** (384-dim, multilingual MiniLM-L12-v2 via ONNX)
4. **Deduplication** prevents registering the same event twice (3 layers: pre-tx, in-tx DB, in-tx local)
5. **Blast radius** measures impact via BFS through the entry graph
6. **Registration** stores entry with embedding in SQLite
7. **Auto-connection** links similar entries via inferred edges

All writes in one transaction (`BEGIN IMMEDIATE` / `COMMIT` / `ROLLBACK`). If anything fails, everything rolls back. Connections use autocommit mode (`isolation_level=None`) with explicit transaction control for WAL compatibility.

## Two modes

### Session mode (default)
One conversation, one `.db` file. 8 event types.

### Proyecto mode
Multi-session projects (books, research, theses). Adds:
- `HIPOTESIS` and `FUENTE` types
- `SUPPORTS` / `CONTRADICTS` / `SUPERSEDES` edges
- Cross-session queries
- Session tracking

```bash
bitacorista init --proyecto "my-research"
bitacorista open "my-research" --session-name "day-2"
bitacorista evidencia E005    # what supports/contradicts hypothesis E005
bitacorista versiones E003    # version chain via SUPERSEDES
```

## All CLI commands

```
init          Create a session or project
add           Add an entry manually
process       Process a user message (detect events)
resumen       Live summary (~20 lines, for AI context injection)
buscar        Semantic search
descartes     List discards for reevaluation
firmes        List confirmed decisions
entries       List all entries
latentes      Find similar unconnected entries
scan          Scan past exchanges for unregistered events
export        Export to Markdown
open          Open a project / create new session
sesiones      List project sessions
evidencia     Show supports/contradicts for a hypothesis
versiones     Show version chain via SUPERSEDES
```

## Requirements

- Python 3.10+
- `sqlite-vec` (optional — enables vector search and deduplication)
- `onnxruntime` + `tokenizers` (optional — enables embeddings)

The core (event detection + SQLite storage) has zero dependencies. Vector search and embeddings are opt-in via `pip install bitacorista[search]` or `bitacorista[embeddings]`.

## License

MIT

---

Built with [Claude Code](https://claude.ai/claude-code)
