bitacorista 2.5.0

Structured memory for AI conversations. Mechanical event detection + semantic search, no LLM required.

Bitacorista-py

A structured memory system for long AI conversations.

---

The problem

Long AI conversations lose context. You make a decision on message 12 — "drop React, go with Vue" — and by message 50 the assistant suggests React again. The longer the conversation, the more gets forgotten or contradicted.

Most memory systems solve this by running another LLM call to decide what to remember. That's a circular dependency: the same system that forgets is responsible for remembering.

Bitacorista breaks the loop. Regex detects events mechanically. SQLite stores them. Embeddings power semantic search. No LLM at runtime. Deterministic. Auditable. Local.

---

What it actually does well

• Structured logging of decisions, discards, corrections, and topic changes in long conversations
• Surviving context compaction — everything is on disk, not in the context window
• Predictable, inspectable behavior you can audit (regex patterns are visible, not a black box)
• Cheap to run — no API costs, no cloud dependency, zero dependencies in the core

What it doesn't do well

• Chaotic, implicit, or scattered conversations — the detection layer works best when language is direct and declarative
• Decisions spread across multiple messages — if you decided something in three partial statements, it may not register as one decision
• Implicit intent — "no LLM" is the advantage, but also the limit when you need to capture something contextual or ambiguous

---

Install

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):

python -m bitacorista.download_model

---

Quick start

CLI

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

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 (EN)	Example (ES)
Decision	"we decided to use Vue"	"decidimos usar Vue"
Discard	"drop React"	"descartamos React"
Correction	"that's wrong, fix it"	"eso está mal"
Topic change	"switching gears"	"cambiemos de tema"
Deliverable	"create the config file"	"arma el archivo"
Discovery	"I found out that..."	"resulta que..."
Question	"what is a webhook?"	"qué es un webhook?"
Hypothesis*	"my hypothesis is..."	"mi hipótesis es..."
Source*	"according to the docs..."	"según la documentación"

Bilingual (Spanish + English). *Last two types available in proyecto mode only. Questions require a ? to avoid false positives.

Detection is regex-based with negation filtering — "No descartamos React" won't register as a discard. If your phrasing doesn't match the patterns, the event won't register. That's the tradeoff for zero runtime cost.

---

Why not Mem0, Zep, or Letta?

	Bitacorista	Mem0 / Zep / Letta
Detection	Regex (deterministic)	LLM call (probabilistic)
Runtime LLM	None	Required
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 design choice: other systems delete what you discard. Bitacorista documents why you discarded it, so you can reevaluate. Discards are signal, not noise.

---

Entry states

State	Meaning
FIRME	User said it explicitly
INFERIDO	System detected it, no explicit confirmation
DESCARTADO	Discarded with context preserved
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      ← CLI commands.
  patterns/   ← Domain-specific pattern packs (optional).

One .db file per session. No intermediate files.

How it works:

1. Regex detection scans user messages for event patterns (bilingual)
2. Negation check filters false positives (grammar-aware)
3. State classification determines FIRME / INFERIDO / DESCARTADO
4. Embedding generation (384-dim, multilingual MiniLM-L12-v2 via ONNX, optional)
5. Deduplication before registering (3 layers)
6. Blast radius — measures what other entries connect to this one
7. Registration in SQLite
8. Auto-connection links similar entries via inferred edges

All writes in one transaction. If anything fails, everything rolls back.

---

Two modes

Session mode (default)

One conversation, one .db file. 9 event types.

Proyecto mode

Multi-session projects — books, research, theses. Adds HIPOTESIS and FUENTE types, SUPPORTS / CONTRADICTS / SUPERSEDES edges, cross-session queries, and session tracking.

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

---

All CLI commands

init          Create a session or project (--patterns dev for domain pack)
add           Add an entry manually
process       Process a user message (detect events)
resumen       Summary with semantic filtering (--query, --json, --max)
buscar        Semantic search
stats         Session dashboard (entries, exchanges, most connected)
descartes     List discards for reevaluation
firmes        List confirmed decisions
pendientes    Review stale INFERIDO entries (confidence decay)
confirmar     Confirm an entry → FIRME
rechazar      Reject an entry → DESCARTADO
merge         Fuse duplicate entries interactively
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

---

Pattern packs

Domain-specific regex patterns that extend the core detection:

bitacorista init --patterns dev    # load development patterns

Available packs:

• dev — programming conversations (commit, deploy, merge, bug, test, refactor)

Packs add patterns to existing types. They don't replace core detection.

---

Requirements

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

The core has zero dependencies. Vector search and embeddings are opt-in.

Works on Windows, macOS, Linux.

---

Best fit

This tool works well for: technical teams, research sessions, documentation of long conversational workflows, and local agents where you want deterministic memory without API costs.

It's not designed for mass-market or casual users, conversations with implicit or scattered decisions, or cases where you need semantic understanding beyond pattern matching.

---

License

MIT — Use it, modify it, build on it.

---

Built with Claude Code.