Metadata-Version: 2.4
Name: recollect
Version: 0.3.0
Summary: Human-like memory for AI applications
License-Expression: MIT
Requires-Python: >=3.12.4
Requires-Dist: anthropic>=0.84.0
Requires-Dist: asyncpg>=0.31.0
Requires-Dist: fastembed>=0.7.4
Requires-Dist: orjson>=3.11.7
Requires-Dist: pgvector>=0.4.2
Requires-Dist: pydantic>=2.12.5
Provides-Extra: openai
Requires-Dist: openai>=2.24.0; extra == 'openai'
Description-Content-Type: text/markdown

# 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

```bash
pip install recollect

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

## Quick Start

```python
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](https://github.com/pgvector/pgvector) extension

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

Set the connection string in your environment:

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

## License

MIT
