Eidetic

Long-term memory for AI conversations. Extracts semantic facts and episodic bubbles from conversation turns, stores them in FAISS with SQLite persistence.

from eidetic import configure, Memory

configure(openai_api_key="sk-...")

memory = Memory()

await memory.add(
    messages=[
        {"role": "user", "content": "Hi, I'm Alice and I love Python"},
        {"role": "assistant", "content": "Great language!"},
    ],
    conversation_id=1,
)

results = await memory.search(query="What language does Alice like?", conversation_id=1)

Install

pip install eidetic-ai

API

configure(**kwargs)

Set global config. Accepts the same keys as EIDETIC_* env vars (without the prefix). Falls back to environment variables if not called.

Memory

Method	Description
add(messages, conversation_id)	Extract semantic facts + bubbles from a user/assistant turn
search(query, conversation_id, limit=10)	Vector similarity search
update(memory_id, text)	Replace text and re-embed
delete(memory_id)	Soft-delete

create_table()

Create all database tables. Call once on first run.

Config

Variable	Default	Description
EIDETIC_OPENAI_API_KEY	—	OpenAI API key
EIDETIC_OPENROUTER_API_KEY	—	OpenRouter API key
EIDETIC_LLM_PROVIDER	openai	openai or openrouter
EIDETIC_LLM_MODEL	gpt-4o-mini	Model for extraction/classification
EIDETIC_EMBEDDING_MODEL	text-embedding-3-small	Model for embeddings
EIDETIC_DATABASE_URL	~/.eidetic/eidetic.db	SQLAlchemy async DB URL
EIDETIC_DEBUG	false	Enable debug logging
EIDETIC_BUBBLE_TTL_DAYS	30	Bubble expiry (0 = never)
EIDETIC_CONNECTION_THRESHOLD	0.6	Min similarity for bubble links
EIDETIC_MAX_CONNECTIONS_PER_BUBBLE	5	Max links per bubble

How it works

Messages → Extractor (LLM) → ToolClassifier (LLM) → FAISS + DB.

Semantic facts are stable long-term truths (name, preferences, skills). The classifier deduplicates and detects contradictions: "loves Python" → "hates Python" triggers REPLACE.

Bubbles are time-bound moments (active problems, deadlines, current tasks). They auto-link to related semantic facts via FAISS similarity and expire after a configurable TTL.

Development

uv sync --extra dev
uv run ruff check src/ tests/
uv run mypy src/
uv run pytest -v

License

MIT