153 lines
4.6 KiB
Markdown
153 lines
4.6 KiB
Markdown
# AGENTS.md
|
|
|
|
This document captures architectural decisions and coding conventions for the Hindsight project.
|
|
|
|
## Documentation
|
|
|
|
- **Main documentation**: [hindsight-docs/docs/developer/](./hindsight-docs/docs/developer/)
|
|
- **Use case patterns**: [hindsight-docs/docs/cookbook/](./hindsight-docs/docs/cookbook/)
|
|
- **API reference**: Auto-generated from OpenAPI spec
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
hindsight/ # Python package for embedded usage
|
|
hindsight-api/ # FastAPI server (core memory engine)
|
|
hindsight-cli/ # Rust CLI client
|
|
hindsight-embed/ # Embedded CLI (no server needed)
|
|
hindsight-control-plane/ # Next.js admin UI
|
|
hindsight-docs/ # Docusaurus documentation site
|
|
hindsight-dev/ # Development tools and benchmarks
|
|
hindsight-integrations/ # Framework integrations (LangChain, etc.)
|
|
hindsight-clients/ # Generated API clients (Python, TypeScript, Rust)
|
|
```
|
|
|
|
## Core Concepts
|
|
|
|
### Memory Banks
|
|
- Each bank is an isolated memory store (like a "brain" for one user/agent)
|
|
- Banks contain: memory units (facts), entities, documents, entity links
|
|
- Banks have a **disposition** (personality traits) and **background** (context)
|
|
- Bank isolation is strict - no cross-bank data leakage
|
|
|
|
### Memory Types
|
|
- **World facts**: General knowledge ("The sky is blue")
|
|
- **Experience facts**: Personal experiences ("I visited Paris in 2023")
|
|
- **Opinion facts**: Beliefs with confidence scores ("Paris is beautiful" - 0.9 confidence)
|
|
|
|
### Operations
|
|
- **Retain**: Store new memories (extracts facts, entities, relationships)
|
|
- **Recall**: Retrieve memories (semantic, BM25, graph, temporal search)
|
|
- **Reflect**: Deep analysis to form new insights/opinions
|
|
|
|
## API Design Decisions
|
|
|
|
### Single Bank Per Request
|
|
- All API endpoints (`recall`, `reflect`, `retain`) operate on a single bank
|
|
- Multi-bank queries are the **client/agent's responsibility** to orchestrate
|
|
- This keeps the API simple and the isolation model clear
|
|
|
|
### Disposition Traits (3-trait system)
|
|
- **Skepticism** (1-5): How skeptical vs trusting when forming opinions
|
|
- **Literalism** (1-5): How literally to interpret information
|
|
- **Empathy** (1-5): How much to consider emotional context
|
|
- These influence the `reflect` operation, not `recall`
|
|
- Background info also only affects `reflect` (opinion formation)
|
|
|
|
## Multi-Bank Architecture Patterns
|
|
|
|
See [hindsight-docs/docs/cookbook/](./hindsight-docs/docs/cookbook/) for detailed guides:
|
|
|
|
- **Per-User Memory**: One bank per user, simplest pattern
|
|
- **Support Agent + Shared Knowledge**: User bank + shared docs bank, client orchestrates
|
|
|
|
## Developer Guide
|
|
|
|
### Running the API Server
|
|
|
|
```bash
|
|
# From project root
|
|
./scripts/dev/start-api.sh
|
|
|
|
# With options
|
|
./scripts/dev/start-api.sh --reload --port 8888 --log-level debug
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# API tests
|
|
cd hindsight-api
|
|
uv run pytest tests/
|
|
|
|
# Specific test
|
|
uv run pytest tests/test_http_api_integration.py -v
|
|
```
|
|
|
|
### Generating OpenAPI Spec
|
|
|
|
After changing API endpoints, regenerate the OpenAPI spec and docs:
|
|
|
|
```bash
|
|
./scripts/generate-openapi.sh
|
|
```
|
|
|
|
This will:
|
|
1. Generate `openapi.json` at project root
|
|
2. Copy to `hindsight-docs/openapi.json`
|
|
3. Regenerate API reference documentation
|
|
|
|
### Generating API Clients
|
|
|
|
After updating the OpenAPI spec, regenerate all clients:
|
|
|
|
```bash
|
|
./scripts/generate-clients.sh
|
|
```
|
|
|
|
This generates:
|
|
- **Rust client**: `hindsight-clients/rust/` (via progenitor in build.rs)
|
|
- **Python client**: `hindsight-clients/python/` (via openapi-generator Docker)
|
|
- **TypeScript client**: `hindsight-clients/typescript/` (via @hey-api/openapi-ts)
|
|
|
|
Note: The maintained wrapper `hindsight_client.py` and `README.md` are preserved during regeneration.
|
|
|
|
### Running the Documentation Site
|
|
|
|
```bash
|
|
./scripts/dev/start-docs.sh
|
|
```
|
|
|
|
### Running the Control Plane
|
|
|
|
```bash
|
|
./scripts/dev/start-control-plane.sh
|
|
```
|
|
|
|
## Code Style
|
|
|
|
### Python (hindsight-api)
|
|
- Use `uv` for package management
|
|
- Async throughout (asyncpg, async FastAPI endpoints)
|
|
- Pydantic models for request/response validation
|
|
- No py files at project root - maintain clean directory structure
|
|
|
|
### TypeScript (control-plane, clients)
|
|
- Next.js with App Router for control plane
|
|
- Tailwind CSS with shadcn/ui components
|
|
|
|
### Rust (CLI)
|
|
- Async with tokio
|
|
- reqwest for HTTP client
|
|
- progenitor for API client generation
|
|
|
|
## Database
|
|
|
|
- PostgreSQL with pgvector extension
|
|
- Schema managed via Alembic migrations in `hindsight-api/alembic/`, db migrations happen during api startup, no manual commands
|
|
- Key tables: `banks`, `memory_units`, `documents`, `entities`, `entity_links`
|
|
|
|
# Branding
|
|
## Colors
|
|
- Primary: gradient from #0074d9 to #009296
|
|
|