recollect

Persistent memory SDK for LLM agents. See the project README for architecture and scoring details.

Install

pip install recollect    # or: uv add recollect

Quick Start

import asyncio
from recollect import CognitiveMemory

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

    await memory.experience(
        "The team decided to migrate from Redis to PostgreSQL for persistence."
    )

    thoughts = await memory.think_about("database decisions", token_budget=500)
    for thought in thoughts:
        print(f"[{thought.relevance:.2f}] {thought.reconstruction}")

    await memory.close()

asyncio.run(main())

API

Memory lifecycle

Decay is reversible. Weak traces past their grace period are archived, not deleted -- the trace and everything derived from it (facts, concept embeddings, situational tokens) survive as substrate. When an archived trace becomes relevant to a query again, it revives automatically: status flips back to active, strength resets to its significance, and the normal reinforcement loop takes over. Memories fade when unused and return when they matter.

Explicit forget() is stronger than fade: a forgotten trace stops surfacing and never auto-revives, though the row is kept. erase() is the only true deletion.

Environment Variables

Configuration

[memory]
decay_rate = 0.05

[retrieval]
max_retrievals = 10

[extraction]
pydantic_ai_model = "ollama:ministral-3"   # pydantic-ai provider:model format

Config sections

Full defaults: config.toml

Config is layered: the packaged defaults always load first, then your TOML file overrides individual keys (explicit config_path wins over MEMORY_CONFIG, which wins over ./memory.toml in the working directory), then environment variables override everything. Your file only needs the keys you change.

from recollect.config import MemoryConfig

config = MemoryConfig(config_path=Path("./my-config.toml"))
memory = CognitiveMemory(config=config)

LLM Provider

from recollect.llm.pydantic_ai import PydanticAIProvider

# Model configured via PYDANTIC_AI_MODEL env var, or pass explicitly:
provider = PydanticAIProvider()  # uses PYDANTIC_AI_MODEL
provider = PydanticAIProvider(model="anthropic:claude-sonnet-4-6")
provider = PydanticAIProvider(model="ollama:llama3")

Reasoning models

Models that use internal chain-of-thought (OpenAI o1/o3, Qwen3, DeepSeek-R1) consume thinking tokens from the max_tokens budget. If extraction returns empty responses, increase the token budget:

# memory.toml
[extraction]
max_tokens = 8192

The default is 8192 to accommodate thinking tokens. Non-reasoning models work fine at this budget; no need to reduce it.

Requirements

• Python 3.12+
• PostgreSQL 17 with pgvector
• DATABASE_URL environment variable

License

MIT