recollect 0.3.0

Human-like memory for AI applications

Recollect

Human-like memory for AI applications.

Why Recollect?

Vector databases retrieve documents by similarity. Recollect models how memory actually works: traces have activation levels, strength that decays over time, and associative links that spread activation to related memories. The result is retrieval that feels natural -- recent and reinforced memories surface first, while dormant ones gracefully fade.

Install

pip install recollect

# With OpenAI or OpenAI-compatible provider support
pip install recollect[openai]

Quick Start

import asyncio
from recollect import CognitiveMemory

async def main():
    memory = CognitiveMemory()
    await memory.initialize()

    # Store an experience -- extracts entities, concepts, significance
    await memory.experience("The team decided to migrate from Redis to PostgreSQL for persistence.")

    # Retrieve with a token budget -- fits the most relevant memories into N tokens
    thoughts = await memory.think_about("database decisions", token_budget=500)
    for thought in thoughts:
        print(f"[{thought.activation:.2f}] {thought.content}")

    await memory.close()

asyncio.run(main())

Features

• Cognitive model -- activation, strength, decay, and significance on every memory trace
• Working memory buffer -- 7 +/- 2 capacity models human short-term memory
• Token budgets -- think_about() selects memories that fit within a token limit
• Spreading activation -- associative links between entities and concepts propagate recall
• LLM extraction -- automatic entity, concept, significance, and valence extraction
• Three LLM providers -- Anthropic (default), OpenAI, OpenAI-compatible (Ollama, LM Studio)
• Local embeddings -- FastEmbed with nomic-embed-text-v1.5-Q (768d), no API calls
• Cross-encoder reranker -- optional reranking for precision-critical retrieval
• Persona facts -- pin/unpin persistent facts; consolidate to merge and prune
• Async-first -- built on asyncpg and Pydantic models with dependency injection via protocols

Requirements

• Python 3.12+
• PostgreSQL 17 with pgvector extension

# macOS
brew install postgresql@17
# Then install pgvector per its docs

Set the connection string in your environment:

export DATABASE_URL=postgresql://user@localhost:5432/mydb

License

MIT