Current Features
This page summarizes what ai-memory-hub can do today. Detailed design notes and implementation plans are linked from the navigation, but this page is the quick inventory for GitHub Pages readers.
Runtime Surfaces
| Area | Available now | Where to start |
|---|---|---|
| HTTP API | Memory insert, search, retrieve, ask, fact search, profile, fact supersession, review, project, health, readiness, observability, and OAuth metadata/routes. | Technical overview |
| MCP server | Memory validate, insert, search, retrieve, ask, fact, profile, review, and project tools plus health/search/timeline-style resources. | Agent integration |
| CLI | aim ingest, aim search, aim retrieve, aim ask, aim serve, aim health, config inspection, and storage checks. |
Technical overview |
| Containers | Non-root container image, readiness and liveness checks, and provider-specific compose examples. | Storage provider examples |
| Docs site | GitHub Pages build through MkDocs Material. | Documentation and planning |
Memory Capabilities
- Schema-validated conversation ingestion from HTTP, MCP, and CLI entrypoints.
- Deterministic normalization, message chunking, deduplication, and content hash handling.
- Append-only accepted memory history for
v1.0.0-beta; destructive memory update/delete endpoints and MCP tools are not part of the beta surface. - Semantic search over chunked memories with stable API and MCP response shapes.
- Conversation retrieval by memory ID.
- Question answering over retrieved memories with citations, confidence, and provenance-oriented metadata.
- Profile and project fact extraction paths for direct recall.
- Sensitive-content quarantine for likely secrets and high-confidence PII before default recall, fact extraction, profile reads, or vector indexing.
- Conversation-aware grouping and retrieval precision improvements.
- Unicode text storage and multilingual retrieval when the configured embedding model supports the stored and queried languages.
Storage And Embeddings
ai-memory-hub uses one metadata provider and one vector provider at runtime. SQLite plus LanceDB is the easiest local path, while larger or shared setups can switch providers through configuration.
| Provider type | Available providers |
|---|---|
| Metadata | SQLite, Postgres, MongoDB |
| Vector | LanceDB, Qdrant, Milvus, Weaviate, PGVector, MongoDB Atlas Vector Search, Elasticsearch, OpenSearch, Redis/RediSearch, Pinecone, Turbopuffer, Vespa, Typesense, in-memory |
| Embeddings | Deterministic local embeddings for smoke tests and HTTP embedding endpoints for useful semantic retrieval |
Provider startup checks cover schema compatibility, vector dimensions, selected distance modes, fallback behavior, health state, and secret redaction.
Security And Privacy
- Auth modes are
nonefor CI/maintainer loopback smoke tests,bearer_tokenfor personal-token compatibility, andoauth_resource_serverfor the hub-issued MCP OAuth flow, plusoidc_resource_serverfor external OIDC discovery/JWKS validation. - Bearer-token authentication protects
/memory/*and/mcp/*when auth is enabled. - Public
/health,/ready,/observability, OAuth protected-resource metadata, authorization-server metadata, and Connect/OAuth browser routes. - Google is the currently supported Connect UI passport provider. Meta and X remain disabled placeholders until their provider flows and tests ship.
- Secret redaction for DSNs, API keys, and sensitive provider configuration.
- Conservative telemetry defaults: no payloads, message text, embeddings, raw tool arguments, or query text in logs by default.
observability.debug_payloadsremains false by default for privacy.- Runtime health and diagnostics avoid exposing credentials.
Shipped HTTP Surface
POST /memory/insertPOST /memory/searchPOST /memory/retrievePOST /memory/askPOST /memory/facts/searchPOST /memory/profile/getPOST /memory/facts/supersedePOST /memory/pending/approvePOST /memory/pending/rejectGET /memory/projectsGET /memory/projects/defaultGET /memory/projects/{project_id}GET /healthGET /readyGET /observabilityGET /.well-known/oauth-protected-resourceGET /.well-known/oauth-protected-resource/mcpGET /.well-known/oauth-authorization-server- Connect UI and local OAuth routes under
/connect,/auth/*, and/oauth/*
Shipped MCP Tool Surface
memory_validatememory_insertmemory_searchmemory_retrievememory_askmemory_fact_searchmemory_profile_getmemory_fact_supersedememory_pending_approvememory_pending_rejectmemory_project_listmemory_project_default_getmemory_project_get
Observability
The service now has a practical local observability baseline:
- Structured text or JSON logs with request IDs, trace IDs, span IDs, operation names, and provider context where available.
- HTTP request-id middleware.
/health,/ready, and/observabilityendpoints.- Optional OpenTelemetry tracing for FastAPI, HTTP clients, and PostgreSQL DB-API calls.
- Metrics for API/MCP outcomes, latency, health, vector rows, provider failures, and fallback state.
- A local observability compose example with OpenTelemetry Collector, Jaeger, Prometheus, and Grafana-compatible metrics flow.
See Observability for setup and operator notes.
Integration And Testing
- Bruno integration smoke coverage for health, HTTP memory flow, and MCP memory flow.
- Provider live-check workflows for common local and hosted-adjacent storage backends.
- Unit, integration, and end-to-end test layout in the repository.
- Release readiness, container, docs publishing, and governance checklists.