# Project: arandu
> Analyzed: 2026-03-19
> Stack: Python 3.11+ · SQLAlchemy (async) · pgvector · Pydantic · hatchling
> Type: library (AI agent memory SDK)
> Suggested budget: ≤ 6 files per task

## Structure
Single-package Python library in `src/arandu/`. Two main pipelines (write, read), background jobs, and a provider system for LLM/embedding backends. Tests are flat in `tests/`. Docs (MkDocs) in `docs/` with EN and PT-BR locales.

## Structural Units
- `src/arandu/` — Package root, public API via `__init__.py`
- `src/arandu/write/` — Write pipeline: extract → entity resolution → reconcile → upsert
- `src/arandu/read/` — Read pipeline: agent → retrieve (multi-signal) → rerank → format
- `src/arandu/background/` — Background jobs: clustering, consolidation, memify, sleep-time
- `src/arandu/providers/` — LLM/Embedding provider implementations (OpenAI shipped)
- `tests/` — Flat test directory, mock-based (no DB required)
- `docs/` — MkDocs documentation (EN + PT-BR)
- `alembic/` — Database migrations

## Pattern Registry

<!-- vibeflow:patterns:start -->
patterns:
  - file: patterns/pipeline-orchestration.md
    tags: [pipeline, orchestration, write, read, async]
    modules: [src/arandu/write/, src/arandu/read/]
  - file: patterns/dependency-injection.md
    tags: [di, protocols, providers, llm, embeddings]
    modules: [src/arandu/providers/, src/arandu/]
  - file: patterns/llm-interaction.md
    tags: [llm, prompts, json, extraction, reconciliation]
    modules: [src/arandu/write/, src/arandu/read/, src/arandu/background/]
  - file: patterns/data-access.md
    tags: [sqlalchemy, async, database, models, queries]
    modules: [src/arandu/write/, src/arandu/read/, src/arandu/background/]
  - file: patterns/error-handling.md
    tags: [errors, exceptions, savepoints, fail-safe, resilience]
    modules: [src/arandu/write/, src/arandu/read/, src/arandu/background/]
  - file: patterns/testing.md
    tags: [testing, mocks, fakes, pytest, async]
    modules: [tests/]
<!-- vibeflow:patterns:end -->

## Pattern Docs Available
- [patterns/pipeline-orchestration.md](patterns/pipeline-orchestration.md) — Multi-stage pipeline pattern (write + read)
- [patterns/dependency-injection.md](patterns/dependency-injection.md) — Protocol-based DI for LLM and Embedding providers
- [patterns/llm-interaction.md](patterns/llm-interaction.md) — LLM call patterns: prompts, JSON parsing, timeouts
- [patterns/data-access.md](patterns/data-access.md) — SQLAlchemy async data access with savepoints
- [patterns/error-handling.md](patterns/error-handling.md) — Exception hierarchy and fail-safe error handling
- [patterns/testing.md](patterns/testing.md) — Mock-based testing with fake providers

## Key Files
- `src/arandu/__init__.py` — Public API surface, all exports
- `src/arandu/client.py` — MemoryClient, WriteResult, RetrieveResult, ScoredFact
- `src/arandu/config.py` — MemoryConfig dataclass with all tuning parameters
- `src/arandu/protocols.py` — LLMProvider + EmbeddingProvider protocols
- `src/arandu/models.py` — 10 SQLAlchemy ORM models (MemoryFact, MemoryEntity, etc.)
- `src/arandu/db.py` — Async engine/session factory, Base class
- `src/arandu/constants.py` — Pydantic schemas (FactCandidate, ExtractionOutput), enums, constants
- `src/arandu/write/pipeline.py` — Write pipeline orchestrator
- `src/arandu/read/pipeline.py` — Read pipeline orchestrator
- `src/arandu/write/extract.py` — LLM extraction (multi-pass + single-pass)
- `src/arandu/write/entity_resolution.py` — 3-phase entity resolution
- `src/arandu/write/reconcile.py` — Mem0-style ADD/UPDATE/NOOP/DELETE reconciliation
- `src/arandu/tracing.py` — PipelineTrace for verbose mode
- `src/arandu/providers/openai.py` — OpenAI concrete provider
- `tests/conftest.py` — FakeLLMProvider, FakeEmbeddingProvider, make_fact()

## Dependencies (critical only)
- `sqlalchemy[asyncio]>=2.0` — Async ORM, session management, models
- `pgvector>=0.3` — Vector similarity search via PostgreSQL extension
- `psycopg[binary]>=3.1` — Async PostgreSQL driver
- `pydantic>=2.0` — Extraction schemas, validation
- `openai>=1.0` (optional) — OpenAI provider implementation

## Known Issues / Tech Debt
- `_cosine_similarity()` is duplicated in `entity_resolution.py` and `consolidation.py`
- `_strip_markdown_fences()` from `extract.py` is imported directly by `reconcile.py` and `entity_resolution.py` (private function cross-module import)
- `models.py` docstring references "10 memory-specific models extracted from the Personal Genius codebase" — legacy reference
