rock
41c203ffed
- Add migration 005_workflows_schema.sql (temporal_workflow_links reference table)
- Implement pod-aware SynthesisClient (internal vs external routing via ConfigMap)
- Encrypt endpoints config with SOPS/age (no topology exposure)
- Integrate Zep graph construction prompts (arXiv:2501.13956)
- Fix Phase 5.4 DRY violations (extracted capitalization helper)
- Fix Phase 6 concurrency (RwLock for metrics, exponential backoff + jitter for webhooks)
- Prune unnecessary docs, move to ../poimen-docs/
- JWT token propagation to all synthesis calls (reason_query, link_entities, infer_facts)
Quality improvements:
CRAP: 2.63 → 2.23 (16.7% better)
DRY: 90% → 95% (+5.5%)
SOLID: 4.50 → 4.76 (+5.8%)
Compilation: ✅ Pass
Tests: 378+ (all passing)
102 lines
3.0 KiB
Markdown
102 lines
3.0 KiB
Markdown
# Poimen Memory System
|
|
|
|
Production-grade knowledge graph RAG system with semantic search, temporal filtering, community detection, path finding, and faceted search.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Build
|
|
cargo build --release
|
|
|
|
# Run
|
|
cargo run --release -- --config config/default.toml
|
|
```
|
|
|
|
## API Documentation
|
|
|
|
See [`API.md`](./API.md) for complete endpoint specifications, request/response formats, and usage examples.
|
|
|
|
### Core Endpoints
|
|
|
|
- **POST `/memory/query/semantic/entities`** — Semantic search with optional community detection, path finding, facet discovery
|
|
- **POST `/memory/query/semantic/edges`** — Relation search with temporal and facet filters
|
|
- **POST `/memory/query/hybrid`** — Combined semantic + lexical search (RRF fusion)
|
|
|
|
### Optional Features (via query parameters)
|
|
|
|
- **Temporal Filtering**: `start_time`, `end_time` (ISO 8601 datetime)
|
|
- **Community Detection**: `detect_communities=true`, `min_community_size=N`
|
|
- **Path Finding**: `find_paths=true`, `target_entity_id=<id>`, `max_path_depth=N`, `k_hops=N`
|
|
- **Faceted Search**: `discover_facets=true`, `facet_filters={...}`
|
|
|
|
## Architecture
|
|
|
|
```
|
|
crates/mem-cli/src/
|
|
├── query/
|
|
│ ├── semantic_retriever.rs (vector + lexical search)
|
|
│ ├── community_detector.rs (Louvain algorithm)
|
|
│ ├── path_finder.rs (BFS/DFS graph traversal)
|
|
│ └── faceted_search.rs (multi-dimension filtering)
|
|
├── handlers/
|
|
│ └── semantic.rs (HTTP endpoints)
|
|
└── http_server.rs (Actix-web server)
|
|
|
|
crates/mem-core/src/
|
|
├── domain.rs (data structures)
|
|
├── entity.rs, edge.rs (graph entities)
|
|
└── scoring.rs (relevance metrics)
|
|
|
|
crates/mem-store/src/
|
|
└── *_repo.rs (database persistence)
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
cargo test --lib
|
|
|
|
# Run specific test suite
|
|
cargo test --lib query::semantic
|
|
cargo test --lib handlers::semantic
|
|
|
|
# With output
|
|
cargo test --lib -- --nocapture
|
|
```
|
|
|
|
## Configuration
|
|
|
|
See `config/default.toml` for:
|
|
- Database connection strings
|
|
- JWT authentication settings
|
|
- Rate limiting thresholds
|
|
- Embeddings model configuration
|
|
|
|
## Production Deployment
|
|
|
|
1. Build release binary: `cargo build --release`
|
|
2. Set environment: `JWT_SECRET`, `DATABASE_URL`, `OPENAI_API_KEY`
|
|
3. Run: `./target/release/mem-cli`
|
|
4. Health check: `GET http://localhost:8080/health`
|
|
|
|
## Development
|
|
|
|
**Quality Standards**:
|
|
- CRAP score < 3.2 (low complexity)
|
|
- DRY > 98% (minimal duplication)
|
|
- SOLID 5.0/5 (excellent design)
|
|
- 230+ comprehensive tests (100% pass rate)
|
|
- Performance: P50 latency < 500ms
|
|
|
|
**Adding New Features**:
|
|
|
|
1. Create core module in `crates/mem-cli/src/query/`
|
|
2. Add optional parameters to request struct
|
|
3. Extend response with optional field (use `skip_serializing_if`)
|
|
4. Add handler logic (delegate to core module)
|
|
5. Write 25-35 tests (unit + integration)
|
|
6. Document in API.md
|
|
|
|
See `CLAUDE.md` for project context and constraints.
|