Skip to content

ai-memory-hub

ci Python 3.14+ License: MIT

Provider live checks: Qdrant MongoDB Weaviate Elasticsearch OpenSearch Milvus Redis Typesense

Local-first memory for AI agents.

ai-memory-hub gives Codex, opencode, Claude, Copilot, and other agent clients a shared memory backend through MCP and HTTP. Store conversations once, then search, retrieve, and ask over them from any compatible client.

                         +------------------+
                         |  ai-memory-hub   |
                         | local/LAN/hosted |
                         +---------+--------+
                                   |
              HTTP API + MCP + auth + storage contract
                                   |
        +--------------------------+--------------------------+
        |                          |                          |
  Codex plugin              Browser extension           Other clients
  skills / MCP setup        Chrome/Edge/etc.            agents, CLIs, apps
        |                          |                          |
        |                          |                          |
  capture + retrieval       capture + retrieval         capture + retrieval
  context injection         context injection           context injection

Adapters do not own memory. Adapters own capture and context injection. The hub owns storage, retrieval, auth, permissions, and memory quality.

Terminology:

  • Capture: an adapter sends selected conversation, page, note, or code context into the hub.
  • Ingestion: the hub validates, normalizes, deduplicates, enriches, embeds, and stores captured content. Fully indexed exact duplicates return the canonical memory ID without repeating derived-record, embedding, metadata, or vector writes.
  • Retrieval: the hub returns relevant memories, facts, citations, or answers.
  • Context injection: an adapter places retrieved memory into the active agent, browser, editor, or CLI session.

Why It Exists

Agent conversations contain useful project context, preferences, decisions, and facts, but that memory is usually trapped inside one tool. ai-memory-hub keeps it in your own local storage and exposes it through stable interfaces.

It is built for:

  • Cross-client handoff between agent tools
  • Local-first project and profile memory
  • MCP-native workflows
  • Deterministic capture, ingestion, retrieval, and context injection boundaries
  • SQLite/LanceDB by default, with optional Postgres, MongoDB, and vector-store providers
  • Bring-your-own embedding model, local or hosted

Provider Selection Rule

At runtime, ai-memory-hub uses one metadata provider and one vector provider. The active providers are selected by providers.metadata_db and providers.vector_db. Provider blocks under storage.metadata_providers and storage.vector_providers are only configuration candidates; listing a block there does not activate that provider.

providers:
  metadata_db: postgres
  vector_db: pgvector

storage:
  metadata_providers:
    postgres:
      url: postgresql://memory:memory@postgres:5432/memory
  vector_providers:
    pgvector:
      url: postgresql://memory:memory@postgres:5432/memory
      table_name: memory_vectors

Optional provider SDKs are installed through extras, not by the presence of a config block. For example, use uv sync --extra postgres for Postgres/PGVector or uv sync --extra qdrant for Qdrant. The checked-in root Containerfile is the quickstart image and installs only the default SQLite/LanceDB runtime dependencies. Provider-specific Compose examples use provider-local Containerfiles so they install only the extras needed by that example.

What It Does

  • Stores structured conversations with validation and deduplication
  • Searches semantic memory with conversation-aware grouping
  • Answers questions with concise MCP defaults or detailed citations, confidence, and provenance on request
  • Extracts useful profile/project facts for direct answers
  • Supports multilingual memory when the configured embedding model supports the languages involved
  • Serves both FastAPI endpoints and an MCP server
  • Supports MCP OAuth setup through the Connect UI with durable dynamic clients, rotating refresh tokens, and revocation
  • Runs locally, in containers, or against your selected storage backend

Runtime Choices

ai-memory-hub is the memory service. It stores conversations, builds embeddings for retrieval, and exposes HTTP/MCP APIs. It does not bundle a hosted embedding model or database service for you.

You choose three things:

Choice Local/default path When to change it
Embeddings Deterministic local embeddings for smoke tests and demos Use a real embedding model for useful semantic search, especially multilingual memory
Metadata storage SQLite Use Postgres for shared durable server setups, or MongoDB when it already owns application persistence
Vector storage LanceDB, Qdrant, Milvus, Weaviate, PGVector, MongoDB Atlas, Elasticsearch, OpenSearch, Redis/RediSearch, Vespa, Typesense, Pinecone, Turbopuffer, or in-memory Use the backend that already fits your local or hosted operations stack

Multilingual Retrieval Rule

ai-memory-hub is not English-only. It stores Unicode text and uses the configured embedding model for semantic retrieval. Multilingual retrieval works when the configured embedding model supports the languages you store and query.

Use the same embedding provider, model, dimension, and options for ingestion and query-time retrieval. If you change the embedding model, provider, dimension, or embedding options for an existing persistent vector index, reindex the stored memory or use a separate vector namespace/index. Do not mix vectors from different embedding spaces, even when two models have the same dimension.

For persistent vector stores, startup records a redacted embedding/vector-index compatibility fingerprint in the metadata store. If the fingerprint changes for an index that already contains vectors, startup fails with a reindex-required message. To migrate intentionally, point the new configuration at an empty vector table, collection, index, or namespace and re-ingest/reindex the memory from durable metadata or source transcripts.

Changing Embedding Models

Changing embedding model, provider, dimension, or embedding options creates a new vector space. Treat it as a reindex operation, even when the old and new models produce the same number of dimensions.

Safe migration checklist:

  1. Stop the hub and any clients that are writing memory.
  2. Back up the metadata database and the current vector store.
  3. Update providers.embeddings, providers.embedding_model, and providers.embedding_dimension for the new model.
  4. Point providers.vector_db at an empty vector table, collection, index, or namespace. Keep the same metadata database if you want to preserve existing conversations, facts, projects, and auth data.
  5. Recalculate embeddings from the stored metadata: uv run aim reindex --config <new-config.yaml> --json.
  6. Run uv run aim storage-check --config <new-config.yaml> --json, then test search and ask before retiring the old vector store.

If startup reports that reindexing is required, do not disable the guardrail to force the old vector index to load. Switch back to the old embedding settings, or move the new settings to an empty vector destination and run aim reindex.

Today the real embedding path is a generic HTTP embeddings endpoint using the OpenAI-compatible /v1/embeddings request/response schema, such as a local Ollama-compatible /v1 endpoint. ai-memory-hub uses a small embeddings-only HTTP client and does not require the OpenAI Python SDK. The deterministic local embedding mode is for smoke tests and demos, not production-quality semantic or multilingual retrieval.

Storage guidance:

  • Use SQLite + LanceDB for the fastest single-machine development setup.
  • Use SQLite + Qdrant when you want a local Docker or Qdrant Cloud vector backend.
  • Use Postgres metadata when multiple clients/users or long-running containers need one shared database.
  • Use Postgres + PGVector when you want one database to store both conversation metadata and vector indexes.

ChromaDB is temporarily unavailable in v0.1.0 because the upstream chromadb package has an unresolved critical advisory with no patched release. The adapter remains in the repository for future re-enable.

  • Use MongoDB metadata or MongoDB Atlas Vector Search when MongoDB already owns the application's persistence layer.
  • Use Milvus/Zilliz, Weaviate, Elasticsearch, OpenSearch, Redis/RediSearch, Vespa, or Typesense when those systems already own vector infrastructure in your environment.
  • Use Pinecone or Turbopuffer when managed/serverless vector search is preferred and hosted credentials, namespace policy, and cost controls are already in place.
  • Use in-memory vectors only for tests, demos, and disposable container smoke runs.

Quick Start

Install:

git clone https://github.com/Artemon-line/ai-memory-hub.git
cd ai-memory-hub
uv sync --dev

Start the API and MCP server:

uv run aim serve --host 127.0.0.1 --port 8000

Insert a memory:

curl -X POST http://127.0.0.1:8000/memory/insert \
  -H "Content-Type: application/json" \
  -d '{
    "source": "codex",
    "messages": [
      {"role": "user", "text": "Remember that I prefer local-first tools."},
      {"role": "assistant", "text": "Stored."}
    ],
    "metadata": {"tags": ["preferences"]}
  }'

Ask over memory:

curl -X POST http://127.0.0.1:8000/memory/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "What tool preference did the user mention?", "top_k": 5}'

MCP endpoint:

http://127.0.0.1:8000/mcp/

MCP exposes the full current tool set by default. To preview the smaller agent-facing surface, set mcp.tool_profile in config.yaml:

mcp:
  tool_profile: advanced # Default; exposes every current MCP tool.
mcp:
  tool_profile: simple # Opt-in preview; exposes only memory_save and memory_ask.

memory_save is an MCP exposure alias for the existing memory_insert ingestion behavior; it does not create a second write path. The simple profile changes only MCP tool registration; HTTP endpoints, MCP resources and prompts, and the hub's internal search, retrieval, fact, and profile implementations remain available. Unknown profile values fail configuration validation.

For user-facing MCP setup, use the local stack example with api.auth: oauth_resource_server and open /connect. The Connect UI shows the active MCP URL, configured passport providers, sign-in status, short-lived hub token workflow, and copyable client snippets. Google is the current live provider; Meta and X config slots are disabled placeholders until their provider-specific flows are implemented. See the Connect UI and OAuth setup guide for packages, provider status, and client verification notes.

To use an external OpenID Connect provider such as Keycloak, select api.auth: oidc_resource_server. The hub validates asymmetric access tokens through discovery/JWKS and maps provider roles to memory scopes; see the external OIDC guide.

Common Workflows

Use the CLI during development:

uv run aim ingest conversation.json --json
uv run aim search "local-first tools" --top-k 5 --json
uv run aim ask "What did I store about local-first tools?" --top-k 5 --json

Save and resume unfinished work without copying a full transcript:

uv run aim handoff create conversation.json --json
uv run aim handoff search "release checks" --json
uv run aim handoff get <memory-id> --json
uv run aim handoff update <memory-id> continuation.json --json

handoff create marks an ordinary conversation with metadata.handoff_at and uses the normal validation, deduplication, authorization, audit, and storage path. handoff update is append-only: it creates a new continuation linked by metadata.parent_conversation_id instead of rewriting the earlier memory. MCP clients can invoke the create_handoff and resume_handoff prompts for the same workflow.

Clients may add descriptive metadata.source_client and opaque metadata.source_session_id values when saving. Search, ask, and handoff search can filter by those fields with --source-client and --source-session-id. These values help another client find the right work; they never grant access or replace the normal owner and project checks.

Handoffs follow the same save policy as every other memory. In require_save_intent mode, an unmarked handoff is rejected; in review_pending mode it remains hidden from normal retrieval until approved. A receiving client can resume shared-project work only when its authenticated principal has normal read access to that project. Handoff audit events contain operation identifiers and outcomes, not conversation payloads, provider session IDs, or private workspace paths.

memory_ask(result_mode="handoff") returns an ephemeral resume_hint with a cited objective, confirmed progress, blocker, immediate next action, and an explicit evidence state. Its default context budget is 512 tokens; stale, incomplete, and unsupported hints say so directly and can be regenerated from current authorized memory without persisting a second summary.

flowchart LR
    A["Agent A<br/>Codex, OpenCode, Claude, Copilot, Hermes"] -->|"create_handoff / handoff create"| H["ai-memory-hub<br/>validated, authorized, durable memory"]
    H --> E["Evidence<br/>messages, summary, citations, lineage"]
    E -->|"handoff-only search + retrieve"| B["Agent B<br/>same or different client"]
    B --> N["Resume from objective,<br/>progress, blocker, next action"]

Why use it:

  • Cross-client: finish in one MCP client and continue in another without a provider-specific session export.
  • Token-aware: retrieve a compact cited continuation packet first, then fetch source evidence only when needed instead of replaying the full transcript.
  • Auditable: the packet points back to immutable stored messages rather than becoming an unsupported summary.
  • Local-first and portable: the same workflow is available through MCP, HTTP, and CLI, with the hub's normal project permissions and redaction.
  • Complementary: runtime handoffs in OpenAI Agents SDK, OpenCode, Hermes, LangGraph, or AutoGen can keep coordinating live agents while ai-memory-hub carries durable state across runs, clients, and model providers.

Typical use cases:

  • Continue a coding task tomorrow without reloading the entire debugging chat.
  • Move unfinished work from Codex to OpenCode, Claude, Copilot, or Hermes.
  • Hand a task from an implementation agent to a review or testing agent with confirmed changes, commands, blockers, and citations.
  • Preserve incident-response state across shifts without treating a generated summary as the only source of truth.
  • Pause a long research or migration workflow and resume from the last verified decision and next action.
  • Create a reviewable checkpoint before changing models, machines, or providers.

See Agent Integration for the token model, implementation diagram, and comparison with popular agent-runtime handoff patterns.

Run with Docker:

docker build -t ai-memory-hub:local -f Containerfile .
docker run --rm -p 127.0.0.1:8000:8000 ai-memory-hub:local

Run the full local stack with Postgres, PGVector, Ollama embeddings, and Google OAuth:

cd examples/local-stack
docker compose up --build

That Compose stack is the main non-quickstart example. It can run credential-free with deterministic embeddings, or use config.oauth-public.yaml for the local-server path:

PUBLIC_BASE_URL="https://YOUR-CUSTOM-DOMAIN.app"
sed "s#https://YOUR-CUSTOM-DOMAIN.app#${PUBLIC_BASE_URL}#g" \
  config.oauth-public.yaml > config.oauth-local.yaml
AMH_CONFIG_FILE=config.oauth-local.yaml docker compose up --build

Generate the local config with the same public HTTPS base URL you register as the Google callback origin, export the Google/OAuth environment variables required by Compose, and keep the hub port bound to 127.0.0.1:8000 when publishing through a tunnel or reverse proxy. Before exposing it beyond loopback, use api.auth: oauth_resource_server with TLS. For real memory quality, keep providers.embeddings: http, point embedding_endpoint.base_url at Ollama or another OpenAI-compatible embeddings endpoint, and set the matching embedding dimension. Reindex or use a separate vector namespace/index if you change embedding model/provider/options on persistent data.

See Storage provider examples for the provider fixture matrix, smoke commands, CI coverage, and hosted-provider notes.

Documentation

Build the docs locally:

uv sync --group docs
uv run python tools/prepare_mkdocs.py
uv run python -m mkdocs build --strict

Status

The project currently includes deterministic append-only ingestion, MCP tools/resources/prompts, HTTP endpoints, CLI commands, fact-backed answers, sensitive-content quarantine, SQLite/Postgres/MongoDB metadata, LanceDB/Qdrant/Milvus/Weaviate/PGVector/MongoDB Atlas/Elasticsearch/OpenSearch/ Redis/Vespa/Typesense/Pinecone/Turbopuffer/in-memory vectors, token-budgeted ask, container CI, provider live-test CI, and GitHub Pages docs publishing.

Planned work includes broader importers, richer summaries, admin-only archive/retention workflows, provider-specific index compatibility checks, and release publishing. General destructive memory update/delete workflows are not part of v1.0.0-beta; corrections should be represented as new memory, fact supersession, or explicit governance events over immutable history.

Known first-release limits: ai-memory-hub does not ship as a hosted memory service, production-quality retrieval requires a bring-your-own embedding model, browser extensions are planned as separate adapters, UI dashboards/SDKs are future work, and archive/restore does not ship in v1.0.0-beta.

Contributing

Contributions are welcome. Keep changes focused, add tests for behavior changes, and run the relevant checks before opening a pull request.

uv sync --dev --group docs
uv run python -m ruff check memory tests tools
uv run python -m pyright
uv run pytest
uv run python -m mkdocs build --strict

Dedication

Dedicated to my little brother,

Andrii Hladenko.

Вічна Слава Героям. Ukraine flag

License

This project is licensed under the MIT License. See LICENSE for details.