bitacorista 2.7.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.

---

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)
• 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?"	"que es un webhook?"
Hypothesis*	"my hypothesis is..."	"mi hipotesis es..."
Source*	"according to the docs..."	"segun la documentacion"

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.

---

Design tradeoffs

Dimension	Bitacorista
Detection	Regex-based, explicit patterns
Runtime LLM	Not required
Storage	Local SQLite
Embeddings	Optional, local
Behavior	Auditable, pattern-driven
Tradeoff	Lower ambiguity handling than semantic systems

Bitacorista is designed for cases where predictability, local storage, and inspectable behavior matter more than broad language understanding.

One specific design choice worth noting: discards are stored with context, not deleted. If you dropped an idea, you can see why — and reevaluate later.

---

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
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
tag           Add tags to an entry (e.g. bitacorista tag E001 sprint-3)
untag         Remove a tag from an entry
tags          List all tags in use
entries       List all entries (--tag to filter by tag)
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.