echostate 0.1.0

Semantic, event-sourced state for intelligent systems

EchoState

Semantic, event-sourced state for intelligent systems

EchoState is a Python library that gives your applications permanent memory and semantic search. Every change you make is saved permanently, and you can search by meaning, not just exact words.

Think of EchoState as Git + SQLite + Vector Search — for runtime state.

Why EchoState?

Building AI agents or long-running applications? You need:

• ✅ Memory that persists - Data survives restarts
• ✅ Search by meaning - Find "refund requests" even if stored as "reimbursement"
• ✅ Complete history - See every change that happened
• ✅ Auditability - Prove what happened and when

EchoState provides all of this with a simple, Pythonic interface.

Features (v0.1)

• ✅ Event-sourced state with deterministic replay
• ✅ SQLite-based persistence
• ✅ Semantic search over explicitly indexed keys
• ✅ History inspection and time-travel snapshots
• ✅ Rebuildable vector index

Quick Start

from echostate import EchoState

# Create a state instance
state = EchoState(
    name="agent_state",
    persist="sqlite:///state.db",
    index_keys=["notes", "profile"],
)

# Write state
state.set("profile.tier", "Gold", metadata={"user_id": "u-42"})
state.append("notes", "Customer requested refund", metadata={"trace_id": "t-123"})

# Semantic search
results = state.search("refund duplicate charge", k=5)
for hit in results:
    print(f"{hit.path}: {hit.text} (score: {hit.score})")

# Inspect history
events = state.history("notes", filters={"user_id": "u-42"}, limit=100)

# Time-travel snapshot
past_state = state.snapshot(at="2026-01-05T10:30:00Z")

Documentation

• 📖 Complete Manual - Beginner-friendly guide with examples and use cases
• 🔧 Implementation Plan - Technical design details
• 💡 Project Idea - Vision and motivation

Installation

pip install echostate

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black echostate/

# Lint
ruff check echostate/

License

MIT