Skip to main content

Eidetic

Production-grade long-term memory system for AI conversations. Extracts semantic facts and episodic bubbles from conversation turns, stores them in a FAISS vector index with SQLite persistence, and surfaces them via a simple Python API or FastAPI HTTP server.

Features

  • Dual Memory Types: Semantic facts (stable, long-term) + Episodic bubbles (time-bound moments)
  • Fast Search: FAISS-powered vector similarity search
  • Smart Updates: LLM-based contradiction detection (ADD / UPDATE / REPLACE / DELETE / NOOP)
  • Memory Connections: Bubbles auto-link to related facts
  • Multi-Provider: OpenAI or OpenRouter (Claude, Gemini, etc.)
  • Flexible Storage: SQLite (default) or PostgreSQL
  • Full async: Python 3.12+, SQLAlchemy 2.0 asyncio

Installation

pip install eidetic-ai

# For the HTTP server (optional):
pip install 'eidetic-ai[server]'

# For PostgreSQL (optional):
pip install 'eidetic-ai[postgres]'

Quick Start (Library)

import asyncio
from eidetic import configure, Memory, create_table

# Configure with your API key
configure(openai_api_key="sk-...")

# Create tables (first time only)
async def main():
    await create_table()

    memory = Memory()

    # Add memories from a conversation turn
    result = await memory.add(
        messages=[
            {"role": "user", "content": "Hi, I'm Alice and I love Python"},
            {"role": "assistant", "content": "Nice to meet you, Alice!"},
        ],
        conversation_id=1,
    )
    print(result)
    # {'semantic': ['User is named Alice', 'User loves Python'], 'bubbles': []}

    # Search stored memories
    results = await memory.search(
        query="What programming language?",
        conversation_id=1,
        limit=5,
    )
    for r in results["results"]:
        print(f"  [{r['type']}] {r['memory']} (score: {r['score']})")

asyncio.run(main())

Environment Variables

export EIDETIC_OPENAI_API_KEY="sk-..."
# Or for OpenRouter:
export EIDETIC_OPENROUTER_API_KEY="sk-or-v1-..."
export EIDETIC_LLM_PROVIDER="openrouter"
export EIDETIC_DATABASE_URL="sqlite+aiosqlite:///path/to/eidetic.db"

Full Example: Chat with Memory

import asyncio
from openai import OpenAI
from eidetic import configure, Memory, create_table

configure(openrouter_api_key="sk-or-v1-...", llm_provider="openrouter")
chat = OpenAI(api_key="sk-or-v1-...", base_url="https://openrouter.ai/api/v1")

async def main():
    await create_table()
    memory = Memory()

    def chat_with_memories(message: str, conv_id: int = 1) -> str:
        # 1. Search relevant memories
        results = asyncio.run(memory.search(query=message, conversation_id=conv_id, limit=5))
        memories_str = "\n".join(
            f"- [{r['type']}] {r['memory']}"
            for r in results["results"]
        )

        # 2. Build prompt with memories
        system = f"You are a helpful AI.\n\nUser Memories:\n{memories_str or 'None yet.'}"

        # 3. Call LLM
        response = chat.chat.completions.create(
            model="anthropic/claude-sonnet-4.5",
            messages=[
                {"role": "system", "content": system},
                {"role": "user", "content": message},
            ],
        )
        reply = response.choices[0].message.content

        # 4. Store new memories
        asyncio.run(memory.add(
            messages=[{"role": "user", "content": message}, {"role": "assistant", "content": reply}],
            conversation_id=conv_id,
        ))
        return reply

    while True:
        msg = input("You: ")
        if msg.lower() == "exit":
            break
        print(f"AI: {chat_with_memories(msg)}")

asyncio.run(main())

HTTP Server

pip install 'eidetic[server]'

# Start the API server
eidetic serve

API Endpoints

Method Path Description
GET /health Health check
POST /conversations Create a conversation
POST /memories Add memories from a conversation turn
GET /memories/search Search memories by similarity
PUT /memories/{id} Update a memory's text
DELETE /memories/{id} Soft-delete a memory
POST /bubbles/expire Run bubble TTL expiry

Full OpenAPI docs at /docs when the server is running.

Docker

docker compose up --build

Set API keys via environment variables (see .env.example).

CLI

eidetic create-conversation           create a new conversation
eidetic add <conv_id> <user> <asst>   add memories from one turn
eidetic search <conv_id> <query>      search stored memories
eidetic expire-bubbles [conv_id]      run bubble TTL expiry

Architecture

┌─────────────┐    ┌──────────────┐    ┌──────────────┐
│  FastAPI    │───▶│ MemoryService │───▶│  Extractor   │
│  (HTTP)     │    │  (orchestr.) │    │  (LLM)       │
└─────────────┘    └──────┬───────┘    └──────────────┘
                          │
             ┌────────────┼────────────┐
             ▼            ▼            ▼
      ┌──────────┐ ┌──────────┐ ┌──────────┐
      │Classifier│ │  Bubble  │ │ Summary  │
      │ (LLM)    │ │  Creator │ │ Service  │
      └──────────┘ └──────────┘ └──────────┘
                          │
             ┌────────────┼────────────┐
             ▼            ▼            ▼
      ┌──────────┐ ┌──────────┐ ┌──────────┐
      │  FAISS   │ │ SQLite   │ │  LLM /   │
      │  Index   │ │   DB     │ │ Embedding │
      └──────────┘ └──────────┘ └──────────┘

Memory types:

  • Semantic — stable long-term facts about the user (name, preferences, skills). Deduplicated and updated via an LLM classifier (ADD / UPDATE / REPLACE / DELETE / NOOP).
  • Bubbles (episodic) — time-bound significant moments. Linked bidirectionally to related memories via FAISS similarity. Automatically expired after a configurable TTL.

Config

All configuration via environment variables with prefix EIDETIC_ or via the configure() function:

Variable / kwarg 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 LLM model name
EIDETIC_EMBEDDING_MODEL text-embedding-3-small Embedding model name
EIDETIC_DATABASE_URL ~/.eidetic/eidetic.db SQLAlchemy async DB URL
EIDETIC_DEBUG false Enable debug logging
EIDETIC_BUBBLE_TTL_DAYS 30 Bubble expiry in days (0 = never)
EIDETIC_CONNECTION_THRESHOLD 0.6 Min similarity for bubble links
EIDETIC_MAX_CONNECTIONS_PER_BUBBLE 5 Max bidirectional links per bubble

Development

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

License

MIT

Metadata

Release files for eidetic-ai 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for eidetic-ai 0.2.1
File Size Uploaded Provenance Actions
eidetic_ai-0.2.1.tar.gz 47.0 kB Without provenance Details for eidetic_ai-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for eidetic-ai 0.2.1
File Interpreter ABI Platform Actions
eidetic_ai-0.2.1-py3-none-any.whl Python 3 none any Details for eidetic_ai-0.2.1-py3-none-any.whl

Total release size: 107.4 kB

Release files / eidetic_ai-0.2.1.tar.gz

Download URL eidetic_ai-0.2.1.tar.gz
Size 47.0 kB
Tags Source
SHA-256 checksum
How to use checksums
60366b2bffca0923a19d543f3fa1833f550fbcd84ee607356ab9b43d51c53d6e
BLAKE2b-256 checksum
How to use checksums
16a50033ee721f690c0679f2c70b5b9265452874d6f11402666fc7b318dc8587
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.30 {"installer":{"name":"uv","version":"0.11.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / eidetic_ai-0.2.1-py3-none-any.whl

Download URL eidetic_ai-0.2.1-py3-none-any.whl
Size 60.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e284ae917f7ee118960517aeb2a5da95ef225cee729e0e1aa88ce621b360f827
BLAKE2b-256 checksum
How to use checksums
adb681568d6bad3571e4959c5d3a5347f2d45f92c29541a361d73f241c9ec66c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.30 {"installer":{"name":"uv","version":"0.11.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for eidetic-ai 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page