animav0.1
Long-term memory for AI agents

Memory that
thinks over time.

Extract facts from conversations, deduplicate and supersede them over time. Hybrid semantic + BM25 retrieval. User profiles. MCP server. A clean Python API.

[ ANIMA · STRUCTURED MEMORY ]
Core CapabilitiesFEATURES [06]
[01]EXTRACTION

Fact Extraction

LLM-backed extraction from conversation turns. OpenRouter by default. No API key required for tests.

[02]HISTORY

Temporal Validity

Facts are superseded, not deleted. Answer 'what did we know before?' with full historical context.

[03]RETRIEVAL

Hybrid Search

FAISS semantic recall + BM25 rerank, fused with confidence and recency scores.

[04]PROFILES

User Profiles

Incremental O(1) profile updates on every add(). Always up-to-date agent context.

[05]GRAPH

Entity Graph

Optional NetworkX graph of entities and relationships built automatically from memory.

[06]INTEGRATION

MCP Server

Six tools for Cursor, Claude Desktop, or any MCP client. Stdio transport, drop-in config.

Quickstart

Up and running
in minutes.

Works without an API key in test mode — uses a random embedder and stores raw conversation as a single fact. Drop in your OpenRouter key for full extraction and dedup.

RequiresPython 3.12+ · uv
Default DBSQLite (SQLAlchemy URL)
Vector storeFAISS (local directory)
LLM backendOpenRouter (swappable)
TransportMCP stdio or HTTP
import asyncio
from anima import Config, Memory

async def main():
    mem = Memory(config=Config.from_env())

    await mem.add(
        "User: I moved to Berlin last week.",
        user_id="alice"
    )
    result = mem.search(
        "Where does Alice live?",
        user_id="alice"
    )
    print(result.injected_prompt)

    page = mem.list("alice", limit=20)
    print(f"{len(page.items)} of {page.total} memories")

asyncio.run(main())
How it worksPIPELINE
01

Conversation Turn

Pass a raw conversation string with a user_id. Works offline with no API key.

02

LLM Extraction

Facts extracted via OpenRouter. Contradictions detected and old facts superseded.

03

Hybrid Index

Embeddings stored in FAISS. BM25 index updated. Confidence and recency tracked.

04

Profile Update

User profile updated incrementally in O(1). Entity graph edges added.

05

Search & Inject

Hybrid FAISS + BM25 retrieval with confidence decay. Returns injected_prompt ready for your LLM.

Python API

mem.add()Extract and store from conversation
mem.search()Hybrid recall + injected prompt
mem.list()Paginated memory listing
mem.pin()Mark permanent — no decay/TTL
mem.export()Full JSON snapshot
mem.import_memories()Restore from export

Env Config

OPENROUTER_API_KEYLLM extraction + profiles
DATABASE_URLSQLite or PostgreSQL URL
VECTOR_STORE_PATHFAISS index directory
DECAY_RATE_PER_WEEK0.05 default
EMBEDDING_DIM1536 — match your model
[ OPEN SOURCE ]

Structured memory for
every AI agent.

Free and open-source. Hybrid retrieval, temporal supersession, MCP server. Plug into any Python agent in minutes.

$uv add anima