chore: unify agents.md and claude.md (#173)
This commit is contained in:
Nicolò Boschi
GitHub
parent
63a65d0723
commit
3290f4bfff
1 changed files with 1 additions and 151 deletions
152
AGENTS.md
152
AGENTS.md
|
|
@ -1,153 +1,3 @@
|
||||||
# AGENTS.md
|
# AGENTS.md
|
||||||
|
|
||||||
This document captures architectural decisions and coding conventions for the Hindsight project.
|
See [CLAUDE.md](./CLAUDE.md) for project documentation and coding conventions.
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue