Technical Overview
This page keeps the technical detail that used to live in the README. The README is intentionally short; use this page when you need implementation, operations, or integration details.
Installation
Clone the repository and install the development environment with uv:
git clone https://github.com/Artemon-line/ai-memory-hub.git
cd ai-memory-hub
uv sync --dev
The project requires Python 3.14 or newer.
Optional extras:
uv sync --dev --extra postgres
uv sync --dev --extra tokenizer
uv sync --dev --all-extras
Use provider extras when selecting optional storage SDKs such as Qdrant,
Milvus, Weaviate, MongoDB, Elasticsearch, OpenSearch, Redis, Vespa,
Typesense, Pinecone, Turbopuffer, Postgres, or PGVector. Use the tokenizer extra for exact
OpenAI-compatible token counting through tiktoken. Use --all-extras for
container builds or provider compatibility checks.
Provider config blocks do not install dependencies. Dependencies are installed
only by the uv sync extras you choose, or by container images that explicitly
install extras. The checked-in root Containerfile is the quickstart image and
installs only the default SQLite/LanceDB runtime dependencies. The free local
Compose examples for PostgreSQL/PGVector, MongoDB, Redis, and SQLite/LanceDB
use provider-local Containerfiles so they install only the extras needed by
that example.
ChromaDB is temporarily unavailable in v0.1.0 because the upstream
chromadb package has an unresolved critical advisory with no patched release.
The adapter code remains in the repository for future re-enable after upstream
publishes a safe version.
How It Works
Captured Conversation JSON
-> Schema Validation
-> Chunk Messages or Token Windows
-> Embed Chunks
-> Store Metadata + Vectors
-> Search / Retrieve / Ask
The hub expects structured conversation JSON. Capture/import adapters convert supported external formats into that shared schema before using the same hub ingestion path. Manual speaker-labelled transcripts are supported; export-specific capture/import adapters are tracked in the roadmap. Browser extension capture is supported as a separate extension-repo workflow that posts normalized web chat payloads to the existing insert API. Remaining capture compatibility work is tracked in the roadmap.
API Endpoints
| Method | Path | Purpose |
|---|---|---|
POST |
/memory/insert |
Validate and store a conversation |
POST |
/memory/import |
Parse and store an uploaded external conversation export |
POST |
/memory/search |
Return ranked semantic matches |
POST |
/memory/retrieve |
Retrieve a stored conversation by ID |
POST |
/memory/ask |
Build an answer from retrieved memory or facts |
POST |
/memory/facts/search |
Search normalized facts |
POST |
/memory/profile/get |
Return profile facts and a compact fact-based summary for a subject |
POST |
/memory/facts/supersede |
Mark a fact as superseded |
GET |
/health |
Liveness endpoint with redacted runtime health |
GET |
/ready |
Readiness endpoint for container orchestration |
Insert Payload
If backend-generated IDs are enabled, omit id and let the server assign the
canonical UUID. When the backend requires caller-supplied IDs, include an id:
{
"id": "11111111-2222-4333-8444-555555555555",
"source": "codex",
"timestamp": "2026-05-17T00:00:00Z",
"messages": [
{"role": "user", "text": "remember this"},
{"role": "assistant", "text": "stored"}
],
"metadata": {
"imported_at": "2026-05-17T00:00:00Z",
"summary": "User asked the assistant to remember a preference.",
"tags": ["preferences"]
}
}
Messages may use text or content; content is normalized to text.
metadata.summary is optional. Use it as a short factual retrieval hint only;
raw messages and normalized facts remain the source of truth for answers and
citations. The server also writes deterministic generated summaries for each
conversation, its topics, and its project. Generated summaries are persisted
separately from raw messages and facts; conversation summaries are exposed back
under metadata.generated_summary for search, retrieve, and CLI display.
The server also writes deterministic metadata.auto_tags and
metadata.tag_sources from source, topics, entities, and fact predicates.
Manual metadata.tags remain authoritative and are not overwritten.
Search and ask tags filters match only explicit metadata.tags; generated
auto_tags support ranking and inspection, but are not filter values.
For continuing source threads, clients may send metadata.upstream_thread_id
or metadata.thread_id. The server preserves upstream IDs, derives
metadata.thread_id when needed, and accepts optional
metadata.parent_conversation_id plus metadata.related_conversation_ids as
conversation UUID references.
metadata.save_intent declares why a client is saving a conversation. Accepted
values are explicit_user_request, user_confirmed, and client_auto_save.
When memory.insert_policy: require_save_intent is configured, API and MCP
inserts without an accepted marker are rejected before storage, vector indexing,
or fact extraction. When memory.insert_policy: review_pending is configured,
unmarked inserts are stored with metadata.memory_status: pending_review and
excluded from default retrieve, search, ask, fact, and profile reads until
approved through /memory/pending/approve or the memory_pending_approve MCP
tool. /memory/pending/reject and memory_pending_reject mark pending inserts
as rejected.
Conversation read operations accept memory_status to intentionally inspect
review states. The default is active. Use pending_review, rejected, or
all with /memory/search, /memory/retrieve, /memory/ask,
memory_search, memory_retrieve, or memory_ask when reviewing held or
rejected inserts.
Store one complete conversation per insert. Do not split one thread into multiple batch items. If an importer has many independent source conversations, it should call the existing single insert path once per source conversation while preserving each original thread/session boundary.
Search Result Shape
/memory/search returns ranked chunk matches in results. Each result includes:
id: canonical conversation IDscore: the source provider's vector distance, retained for compatibility; fused ordering does not compare this value with lexical or metadata scoreschunk_index,role, andtext: the matched chunkconversation: the stored conversation payload, includingmetadata.generated_summarywhen a server-generated conversation summary is available, andmetadata.auto_tagswhen deterministic tags were generatedconversation_score: best score for that conversation among retrieved chunksconversation_match_count: number of retrieved chunks from that conversation
Search applies conservative conversation grouping before trimming to top_k, so
closely matched chunks from the same conversation can surface together without
hiding strong unrelated matches.
Use result_mode=threads to group matching conversations by metadata.thread_id.
To save unfinished work for later, insert it as a normal memory with an RFC 3339
metadata.handoff_at timestamp. Search or ask with handoff_only=true to limit
retrieval to these handoff-marked memories. Handoffs therefore use the same
storage, indexing, permissions, and retrieval path as every other memory.
MCP memory_search adds a response_format enum. The default,
response_format="concise", returns each row as matched chunk fields plus a
small citation object with conversation ID, source, title, timestamp,
thread ID, and generated summary text when available:
{
"id": "11111111-2222-4333-8444-555555555555",
"score": 0.0,
"chunk_index": 0,
"role": "user",
"text": "Remember that I prefer local-first tools.",
"matching_chunks": 1,
"citation": {
"id": "11111111-2222-4333-8444-555555555555",
"source": "codex",
"timestamp": "2026-06-08T12:00:00Z",
"thread_id": "codex:session-42",
"summary": "User said they prefer local-first tools."
}
}
Use response_format="detailed" when an MCP client needs the full
conversation envelope, generated-summary metadata, auto-tag provenance, and
chunk manifests for audit or diagnostics.
MCP memory_retrieve also accepts response_format. The default
response_format="concise" returns a compact memory object with public recall
fields, memory status, message count, and a small list of role/text messages.
Use response_format="detailed" for the full redacted stored record. HTTP
/memory/retrieve keeps the detailed administrative shape.
Ask Result Shape
/memory/ask returns:
answer: human-readable answer text. For fact-backed answers this uses normalized display values while preserving raw source text in stored memory and fact evidence.results: chunk-shaped retrieval hits. Fact-only answers can legitimately return an emptyresultslist because the answer came from normalized facts, not retrieved chunks.citations: compact provenance for chunks or facts used in the answer.provenance: grouped source-conversation provenance.confidenceandconfidence_reason: confidence label plus the reason, such as a direct user statement, assistant statement, inferred recurring topic, or conflict.answer_basis: one ofdirect_memory,fact_layer,mixed,conflict, ornot_found.evidence: stable evidence entries used by the answer. Chunk-backed answers returntype: "chunk"entries; fact-backed answers returntype: "fact"entries.structured_evidence: split evidence for clients that do not want to inspect mixed lists.structured_evidence.factscontains normalized fact evidence andstructured_evidence.resultscontains chunk-shaped retrieval hits.facts: active normalized facts used by fact-backed answers, includingsource_quality,confidence_reason,created_at,updated_at,last_confirmed_at,superseded_at,object_raw,object_normalized, and save-intent provenance when the source memory included it. Facts derived frommetadata.save_intent: client_auto_saveuse lower confidence than explicit user-requested saves.
memory_ask compares weak, assistant-derived, or conflicting normalized facts
with ranked conversation chunks before choosing answer_basis. A corroborated
fact-and-chunk answer uses mixed; disagreement uses conflict and includes
both sides in evidence and structured_evidence. Unambiguous high-confidence
direct-user and corrected facts retain the low-latency fact_layer fast path.
Newly extracted facts are validated against their source message before they
become active. Detailed fact responses include the supporting evidence_span,
source_role, assertion and temporal classifications, numeric
confidence_score, extractor/rule identifiers, and validation_status.
Negated and hypothetical candidates are rejected; quoted, uncertain, temporary,
inferred, and assistant-derived facts are retained with lower confidence as
appropriate. Older fact rows remain readable as validation_status: legacy
without synthetic evidence fields.
Pass max_context_tokens to /memory/ask to build the answer from only the
chunks that fit the requested context budget. When budgeting is active, the
response can include context_tokens_used, chunks_selected, chunks_dropped,
and tokenizer_used.
MCP memory_retrieve, memory_ask, memory_fact_search, and
memory_profile_get support the same response_format enum as search.
Concise ask responses are
answer-centric: they keep answer, confidence, confidence_reason,
answer_basis, and small result/fact/citation counts, but omit full
citations, evidence, structured_evidence, provenance, chunk result
arrays, and token-budget diagnostics. Concise fact/profile reads deduplicate
and limit fact rows to 10 by default, drop qualifiers, source message indexes,
owner/project fields, and summary provenance while keeping fact display values,
freshness, source quality, confidence, and supersession status. Use
response_format="detailed" for the full evidence-rich answer and fact
provenance.
CLI
Use python -m memory.cli during development, or the packaged aim console
script after installation.
python -m memory.cli ingest conversation.json --json
python -m memory.cli reindex --json
python -m memory.cli import manual copilot-chat.txt --source vscode-copilot --json
python -m memory.cli import copilot-activity-csv copilot-activity-history.csv --json
python -m memory.cli import copilot-cli-events-jsonl "$HOME/.copilot/session-state/<SESSION_ID>/events.jsonl" --json
python -m memory.cli import deepseek-harness-session-jsonl dsh-session/session.v4.jsonl --json
python -m memory.cli import droid-exec-json droid-capture.json --json
python -m memory.cli import hermes-session-jsonl hermes-backup.jsonl --json
python -m memory.cli import deepseek-share-json deepseek-share.json --json
python -m memory.cli import claude-code-session-jsonl "$HOME/.claude/projects/<PROJECT>/<SESSION_ID>.jsonl" --json
python -m memory.cli import codex-rollout-jsonl "$CODEX_HOME/sessions/2026/04/12/rollout-<SESSION_ID>.jsonl" --json
python -m memory.cli import gemini-cli-session-json gemini-session.json --json
opencode export <SESSION_ID> | python -m memory.cli import opencode-session-json - --json
python -m memory.cli import pi-session-jsonl "$HOME/.pi/agent/sessions/--work-project--/<SESSION_ID>.jsonl" --json
python -m memory.cli import pi-session-jsonl "$HOME/.omp/agent/sessions/--work-project--/<SESSION_ID>.jsonl" --json
python -m memory.cli import pi-session-jsonl openclaw-session.jsonl --source openclaw --json
python -m memory.cli import qwen-code-session-export qwen-session.json --json
python -m memory.cli import qwen-code-session-export qwen-session.jsonl --json
python -m memory.cli search "local-first tools" --top-k 5 --json
python -m memory.cli retrieve <MEMORY_ID> --json
python -m memory.cli ask "What did I store about local-first tools?" --top-k 5 --json
python -m memory.cli serve --host 127.0.0.1 --port 8000
For short, source-by-source instructions and the default Linux, macOS, and Windows session locations, see Import Conversations.
Manual imports accept multiline messages labelled with common speaker names such
as User:, You:, Human:, Assistant:, Copilot:, Claude:, or Gemini:.
Use - as the file name to read the transcript from stdin.
Codex CLI and the Codex app persist complete session rollouts as JSONL under
$CODEX_HOME/sessions/YYYY/MM/DD/. Import those files with
codex-rollout-jsonl; the importer keeps only canonical user and assistant text
messages and omits reasoning, system/developer instructions, tool calls and
results, approvals, usage, injected startup context, and duplicate presentation
events. Sessions run with
--ephemeral do not create rollout files. codex exec --json is an output
protocol and is not guaranteed to contain the submitted prompt, so use the
persisted rollout unless the prompt was captured separately in a versioned
envelope. A result-only capture is rejected instead of creating a one-sided
conversation.
Codex rollout compatibility contract
The importer contract was verified against Codex CLI 0.152.0 on
2026-10-02. Both codex --version and the sampled rollout's
session_meta.payload.cli_version reported 0.152.0; the rollout identified
itself with source: "cli" and originator: "codex-tui". This is an observed
compatibility baseline, not a claim that Codex's local rollout format is a
stable public API. Validate a minimized fixture before declaring support for a
newer Codex version.
codex-rollout-jsonl consumes this bounded subset of the observed contract:
| JSONL record | Fields consumed | Behavior |
|---|---|---|
session_meta |
payload.id, timestamp, cwd, source, originator, cli_version, model_provider, and optional git.branch/git.commit_hash |
Maps safe session provenance into canonical metadata. Account identifiers, base instructions, and unrecognized fields are not copied. |
response_item message |
payload.role, textual input_text/output_text content blocks, and optional internal_chat_message_metadata_passthrough.turn_id |
Keeps user input_text and assistant output_text only. When several user-role records share a turn ID, only the last is kept so injected startup context is excluded. |
| Every other record | None | Ignores event copies, developer/system instructions, reasoning, tools, approvals, usage, turn context, and unknown future record types. |
Malformed JSON fails with its line number. A result-only stream without both a user message and an assistant message is rejected. Records without a turn ID retain file order for compatibility with older or simplified rollouts.
The regression suite also includes a salted, fully synthetic Codex 0.152.0 rollout shaped like a resumed tool-using session. It verifies that five user turns, five visible assistant progress messages, and five final answers survive as 15 ordered conversation messages, while 14 reasoning records, 14 tool calls, 14 tool outputs, developer instructions, and injected environment context do not enter canonical memory.
Microsoft Copilot activity exports must use the columns Conversation, Time,
Author, and Message. The importer groups rows by conversation and restores
chronological order. Attachment-only turns appear as empty Human rows in some
Microsoft exports; the importer omits those placeholders because the CSV does
not contain the attachment, while preserving the surrounding textual messages.
GitHub Copilot CLI stores resumable sessions under
$COPILOT_HOME/session-state/<session-id>/events.jsonl, with
~/.copilot/session-state/ as the default location. Import a copied, inactive
event log with copilot-cli-events-jsonl. This is separate from the Microsoft
Copilot activity-history CSV importer above. The JSONL importer keeps visible,
top-level user.message and assistant.message text in event order and
deduplicates stable message or event IDs. It omits system and synthetic user
prompts, reasoning, sub-agent messages, tool calls and results, permissions,
compaction data, errors, usage, telemetry, and unknown event types.
The bundled Draft 2020-12 importer schema covers both initial session.start
and resumed-session metadata envelopes plus the observed minimal and current
message envelopes. Safe provenance includes the session ID, start time, working
directory, repository, Git root and branch, selected model, CLI version, and
title when those fields are present. Recognized malformed records and invalid
timestamps fail with their physical line number; unknown event types remain
forward-compatible. A malformed JSONL file, including a historical tool result
split across physical lines by an unescaped newline, fails instead of being
silently repaired into a partial conversation.
For a reviewable manual fallback, run /share file <PATH> (or its /export
alias) in Copilot CLI and import the resulting Markdown with manual. Review
either artifact for sensitive prompts, paths, and output before copying or
retaining it. Multipart HTTP upload remains outside the importer contract.
Factory Droid does not currently document a portable export for historical
interactive CLI sessions. The droid-exec-json importer therefore accepts only
the versioned ai-memory-hub.droid-exec-capture envelope for headless
droid exec runs. It rejects raw result-only JSON because that output omits the
submitted prompt.
For a one-shot run, record the exact submitted prompt and Droid's JSON result in
one capture. This example uses jq only to assemble the local capture file:
prompt='Explain this repository'
droid exec "$prompt" --output-format json > droid-result.json
jq -n --arg prompt "$prompt" --slurpfile result droid-result.json \
'{
format: "ai-memory-hub.droid-exec-capture",
version: 1,
kind: "one-shot",
prompt: $prompt,
result: $result[0],
metadata: {cwd: "/workspace/project", model: "configured-model"}
}' > droid-capture.json
python -m memory.cli import droid-exec-json droid-capture.json --json
Only a successful, non-empty one-shot result becomes an assistant message. The importer preserves safe session ID, duration, reported turn count, model, cwd, title, and timestamp metadata when supplied. Error results are rejected, and unknown result fields are ignored.
For a multi-turn integration, launch the documented bidirectional protocol:
droid exec \
--input-format stream-jsonrpc \
--output-format stream-jsonrpc \
--auto low
The recorder must wrap each JSON-RPC object with its direction rather than concatenating stdin and stdout into an ambiguous log:
{
"format": "ai-memory-hub.droid-exec-capture",
"version": 1,
"kind": "stream-jsonrpc",
"frames": [
{
"direction": "client-to-droid",
"message": {
"jsonrpc": "2.0",
"id": "turn-1",
"method": "droid.add_user_message",
"params": {"text": "Explain this repository"}
}
},
{
"direction": "droid-to-client",
"message": {
"jsonrpc": "2.0",
"method": "droid.session_notification",
"params": {
"notification": {
"type": "assistant_text_delta",
"messageId": "assistant-1",
"blockIndex": 0,
"textDelta": "This repository..."
}
}
}
},
{
"direction": "droid-to-client",
"message": {
"jsonrpc": "2.0",
"method": "droid.session_notification",
"params": {
"notification": {"type": "agent_turn_completed", "reason": "completed"}
}
}
}
]
}
The importer pairs droid.add_user_message requests with successfully completed
turns and coalesces assistant_text_delta values by message and block. It skips
system prompts, thinking, tool calls and results, permissions, errors, usage,
control traffic, incomplete turns, and unknown notifications. This contract
does not scrape the Droid TUI, follow organization /share links, or import
arbitrary historical Droid sessions. Raw-content OpenTelemetry export is not a
normal capture path: it is opt-in, can expose sensitive content, and can
truncate attributes. Multipart HTTP upload remains tracked separately.
DeepSeek Harness can download a session tree as
dsh-session-<SESSION_ID>.zip from its /export browser page. Only extract an
archive you generated or otherwise trust: inspect its entries first, reject
absolute paths or .. traversal entries, and extract it into a new empty
directory rather than over existing files. The importer deliberately does not
open ZIP archives or attachments. Pass the extracted root session.jsonl or
session.vN.jsonl file to deepseek-harness-session-jsonl:
unzip -l dsh-session-<SESSION_ID>.zip
mkdir -p dsh-session
unzip -q dsh-session-<SESSION_ID>.zip -d dsh-session
python -m memory.cli import deepseek-harness-session-jsonl dsh-session/session.v4.jsonl --json
Choose the root file actually present in the archive; unversioned version 0
logs use session.jsonl, while later formats use session.vN.jsonl. Descendant
agent logs under subagents/<SESSION_ID>/ are independent conversations and
may be imported separately with the same command. The importer records their
parent session ID and descendant relationship but does not merge the tree.
The bundled Draft 2020-12 schema supports canonical Harness session versions
0 through 4. It keeps visible user and assistant text, while omitting system
and request context, internal user messages, reasoning, commands, tools,
compaction content, usage, attachments, duplicate message updates, and unknown
event types. Exported logs with seq and time coordinates must contain a
complete dense sequence; raw canonical files without coordinates retain their
physical order. Mixed or non-monotonic ordering and malformed recognized
records fail with their physical line number. Multipart archive upload remains
outside this importer contract.
This format is distinct from deepseek-share-json, which consumes the public
DeepSeek chat share-content response. DeepSeek web's account-wide Download
all data ZIP contains user.json plus graph-shaped conversations.json and
is tracked separately in #197.
No native per-conversation JSON download was present in the web UI verified on
2026-11-01. Account data, public-share JSON, third-party extension formats, and
Harness session JSONL are not interchangeable.
For a public DeepSeek share link, save the response from its share-content API
as JSON, then pass that file to deepseek-share-json. The importer keeps request
and response text, represents file-only turns by their attachment names, and
does not copy search-result snippets into memory. It rejects the account-wide
export with a non-content-echoing error that directs users back to the public
share response. For example:
curl -fsS \
'https://chat.deepseek.com/api/v0/share/content?share_id=<SHARE_ID>' \
-o deepseek-share.json
python -m memory.cli import deepseek-share-json deepseek-share.json --json
OpenCode session exports can be streamed directly from opencode export or
read from a saved JSON file. The importer keeps user and assistant text in
export order, skips internal reasoning, tool-only turns, and synthetic or
ignored text parts, and records the OpenCode session ID, title, working
directory, and model as provenance when present. Sanitized exports are also
accepted; their redacted text remains redacted.
Pi and Oh My Pi store machine-readable sessions as version 3 JSONL trees under
~/.pi/agent/sessions/ and ~/.omp/agent/sessions/, respectively. Import a
copied, inactive session with pi-session-jsonl. The importer follows the last
entry's parentId ancestry to reconstruct the active branch, so abandoned fork
branches are not flattened into the conversation. It keeps user and assistant
text blocks in ancestry order and omits system/developer messages, thinking,
tool calls and results, custom/bootstrap records, compaction bodies, usage, and
provider-private data. Oh My Pi title/header markers and OpenClaw-namespaced
records are used for variant detection; use --source openclaw for older
OpenClaw archives without a distinguishing marker.
Malformed JSON reports its line number. Duplicate entry IDs, missing parents, cycles, and unsupported session versions are rejected instead of guessing at a partial conversation. Orphaned branches therefore fail closed even when they are not the last branch. The importer accepts the optional fixed-width Oh My Pi title record before the logical session header and preserves only bounded safe provenance such as the session ID, working directory, model, title, and Git branch or commit. Its bundled Draft 2020-12 importer schema validates the title record, version 3 session header, entry-tree fields, and recognized message envelopes before typed parsing. Schema failures report the source line and field path when available.
Pi and Oh My Pi HTML exports are presentation-only and do not preserve the session tree, so import their JSONL source instead. Current OpenClaw runtime sessions live in a SQLite database; do not copy or read a live database file through this importer because a main-file-only copy can omit write-ahead-log data. Use an archived/legacy JSONL artifact or a coordinated OpenClaw export or backup. The importer does not open paths found inside an export.
Claude Code persists resumable session transcripts as JSONL under
~/.claude/projects/<project>/<session-id>.jsonl. Import a copied, inactive
transcript with claude-code-session-jsonl. The importer retains non-empty user
and assistant text in file order, deduplicates repeated visible records by UUID,
and records the session ID, working directory, Git branch, and model when
present. Its bundled Draft 2020-12 importer schema defines the accepted message
envelope, role matching, content shapes, and compaction-summary exclusion. It
omits system prompts, thinking, tool calls and results, progress, usage,
compaction summaries, and file snapshots. Malformed JSON and recognized message
records that do not match the importer schema report their line number. Claude
Code's /export transcript.txt output is suitable for the manual importer
when a readable transcript is preferred, but it does not preserve the same
structured provenance. Review the transcript for sensitive content before
copying or importing it.
Gemini CLI sessions can be exported with /export-session gemini-session.json
and imported with gemini-cli-session-json. JSON written by
/chat share gemini-session.json is also accepted, as are legacy local saved-chat
JSON objects with the same session envelope. Current Gemini CLI autosaved session
files may use an internal JSONL format; use /export-session rather than passing
those files to this JSON importer. The importer maps user and gemini/model
roles to canonical messages, keeps text blocks in export order, and records the
session ID, project hash, workspace directories, start time, and first visible
model name when available. It omits injected session context, thoughts, tool
calls and results, token counts, diagnostics, and unknown fields.
Gemini's export formats may contain prompts, responses, workspace paths, and other sensitive context. Review the JSON before sharing or retaining it outside the CLI's local state. The bundled importer schema accepts only the documented session-object and shared-history envelopes; malformed recognized messages fail with their message index.
Qwen Code supports self-contained native transcript exports through
/export json and /export jsonl. Import either format with
qwen-code-session-export. The JSON form contains one session object; the
canonical JSONL form begins with a session_metadata record followed by the
same normalized message objects. A bounded message-only JSONL stream is also
accepted when metadata was captured separately. The importer keeps textual
message.content or message.parts[].text from user and assistant records,
deduplicates repeated message UUIDs, and records the session ID, start time,
working directory, Git repository and branch, model, and channel when present.
The bundled Draft 2020-12 importer schema validates the JSON envelope, JSONL
metadata, role matching, stable UUIDs, timestamps, and recognized message
content before typed parsing. System records, goal-state audit data, tool calls
and raw input/output, usage, aggregate file lists, and unknown future message
types are not copied into canonical memory. qwen sessions list --json is a
session metadata listing, not a transcript export; use /export json or
/export jsonl for conversation content. HTML and Markdown exports are
presentation-oriented and can be reviewed and imported with manual when a
human-readable fallback is preferable.
Review imported output before retaining sensitive conversations. The repository fixtures are synthetic and contain no text copied from personal exports.
Hermes Agent's sessions export command writes one complete session object per
JSONL line. Import one session directly from standard input, or save and import
a multi-session backup:
hermes sessions export - --session-id <SESSION_ID> --redact \
| python -m memory.cli import hermes-session-jsonl - --json
hermes sessions export hermes-backup.jsonl --redact
python -m memory.cli import hermes-session-jsonl hermes-backup.jsonl --json
Use --redact whenever an export may be shared or retained outside Hermes'
local state. The importer preserves each exported session as a separate hub
conversation and keeps safe provenance such as its session ID, Hermes source,
title, model, working directory, Git root and branch, parent session ID, and
UTC start time. It imports non-empty user and assistant text that remains in
Hermes' visible history, including compaction-archived turns, while excluding
rewound/edited-away rows and synthetic compressed context. System prompts,
tool calls and results, reasoning, timings, billing and token data, user/chat
identifiers, and unknown fields are not copied into canonical memory. Hermes
Markdown exports are presentation formats; use the documented JSONL backup for
structured import.
Multipart HTTP imports
Authenticated API clients can use the same registered parsers as the CLI with
POST /memory/import. The request must be multipart/form-data with an
explicit parser text field and one uploaded file part. The server never
guesses a parser from the filename or media type, and the uploaded filename is
metadata only: it is never opened as a server path or treated as a URL.
JSON, JSONL, CSV, and speaker-labelled plain-text examples:
curl -fsS -X POST http://127.0.0.1:8000/memory/import \
-H "Authorization: Bearer $MEMORY_API_TOKEN" \
-F "parser=opencode-session-json" \
-F "file=@opencode-session.json;type=application/json"
curl -fsS -X POST http://127.0.0.1:8000/memory/import \
-H "Authorization: Bearer $MEMORY_API_TOKEN" \
-F "parser=hermes-session-jsonl" \
-F "file=@hermes-backup.jsonl;type=application/x-ndjson"
curl -fsS -X POST http://127.0.0.1:8000/memory/import \
-H "Authorization: Bearer $MEMORY_API_TOKEN" \
-F "parser=copilot-activity-csv" \
-F "file=@copilot-activity.csv;type=text/csv"
curl -fsS -X POST http://127.0.0.1:8000/memory/import \
-H "Authorization: Bearer $MEMORY_API_TOKEN" \
-F "parser=manual" \
-F "file=@transcript.txt;type=text/plain"
Optional source and title text fields have the same meaning as their CLI
options. An optional schema JSON part is accepted only when the selected
parser publishes a bounded override contract. Hermes currently supports
version 1 top-level field aliases, role aliases, and explicit ISO 8601, Unix
seconds, or Unix milliseconds timestamps:
{
"version": 1,
"message_container": "turns",
"session_id_field": "session_key",
"role_field": "speaker",
"content_field": "body",
"role_map": {
"human": "user",
"ai": "assistant"
},
"timestamp": {
"field": "created_at",
"format": "iso8601"
}
}
curl -fsS -X POST http://127.0.0.1:8000/memory/import \
-H "Authorization: Bearer $MEMORY_API_TOKEN" \
-F "parser=hermes-session-jsonl" \
-F "file=@custom-hermes.jsonl;type=application/x-ndjson" \
-F "schema=@hermes-parser-schema.json;type=application/json"
python -m memory.cli import hermes-session-jsonl custom-hermes.jsonl \
--schema hermes-parser-schema.json --json
Overrides cannot contain remote or filesystem references, code, templates,
queries, or regular expressions, and cannot alter authentication, canonical
validation, save-intent policy, sensitive-content handling, hashing, storage,
or project ownership. The endpoint requires memory:write, accepts UTF-8 input
only, limits files to 20,000,000 bytes, limits override schemas to 65,536 bytes,
and returns bounded per-conversation IDs and statuses without echoing source
text or schema contents. All sessions are parsed before insertion begins; if a
later independent insertion fails, its index receives a redacted error receipt.
Each receipt reports inserted, deduplicated, appended, stale, conflict,
or error. The response also separates processed from inserted and includes
aggregate counts for every outcome. See
Import Conversations for the
recurring-import and CLI exit-code contract.
Shared options include --config <path>, --json, --quiet, and --verbose.
search also supports --source, --date-from, --date-to, repeated --tags,
--thread-id, and --result-mode chunks|compact|conversations|threads.
Diagnostics:
python -m memory.cli tokenizer-check --json
python -m memory.cli health --json
python -m memory.cli config-show --json
python -m memory.cli storage-check --json
Authenticated clients can inspect visible project workspaces through GET /memory/projects, GET /memory/projects/default, GET /memory/projects/{project_id}, and the matching MCP project helper tools.
Local bearer-token and project administration is CLI-first. Token creation prints the raw bearer token once; token list and revoke commands only expose stable token ids and non-secret prefixes.
python -m memory.cli admin user create jane --display-name "Jane" --json
python -m memory.cli admin user list --json
python -m memory.cli admin token create --user jane --display-name laptop --json
python -m memory.cli admin token list --user jane --json
python -m memory.cli admin token revoke <TOKEN_ID_OR_PREFIX> --json
python -m memory.cli admin project create shared-321 --owner jane --name "Shared 321" --json
python -m memory.cli admin project list --user jane --json
python -m memory.cli admin project member add shared-321 --user carl --role writer --json
python -m memory.cli admin project member list shared-321 --json
Fact review helpers:
python -m memory.cli fact-search --subject user --json
python -m memory.cli fact-search --source codex --status superseded --json
python -m memory.cli profile-get --subject user --predicate owns_item --source-quality corrected_by_user --save-intent-source codex --json
python -m memory.cli fact-supersede <OLD_FACT_ID> <NEW_FACT_ID> --json
MCP Interface
When interfaces.mcp is enabled, the streamable HTTP MCP endpoint is mounted at:
http://127.0.0.1:8000/mcp/
For user-facing MCP setup, run with api.auth: oauth_resource_server and open
/connect. The Connect UI shows the configured MCP resource URL, enabled
passport providers, sign-in status, hub-issued token workflow, and client setup
snippets. Google is the current live provider; meta and x are disabled
provider slots until their provider-specific flows are implemented. Client
snippets remain marked Unverified until checked against current client
releases. See the Connect UI and OAuth setup guide for
packages, Docker setup, provider status, and client verification notes.
For an external OpenID Connect provider such as Keycloak, use
api.auth: oidc_resource_server. This mode validates asymmetric access tokens
through provider discovery/JWKS and advertises the external issuer to MCP
clients; see External OIDC and Keycloak.
Core tools:
memory_validate(conversation_json)memory_insert(conversation_json)memory_search(query, top_k=5, limit, cursor, result_mode="chunks", response_format="concise", source, date_from, date_to, tags, thread_id, handoff_only=false)memory_retrieve(id, response_format="concise", project_id, memory_status)memory_ask(question, top_k=5, max_context_tokens=None, result_mode="chunks", response_format="concise", source, date_from, date_to, tags, thread_id, handoff_only=false, project_id)memory_fact_search(query=None, subject=None, predicate=None, include_superseded=False, response_format="concise", limit=None, source, date_from, date_to, confidence, status, source_quality, save_intent, save_intent_source, freshness_from, freshness_to, project_id)memory_profile_get(subject="user", predicate, response_format="concise", limit=None, source, date_from, date_to, confidence, status, source_quality, save_intent, save_intent_source, freshness_from, freshness_to, project_id)memory_fact_supersede(fact_id, superseded_by)memory_project_list()memory_project_default_get()memory_project_get(project_id)
memory_profile_get returns facts plus a summary object. Its default
concise projection keeps canonical direct-user and user-correction facts; use
an explicit predicate or source_quality filter to include assistant statements
or inferred topics. Detailed reads retain the complete timestamped fact history.
The summary includes freshness, source-quality counts, filters, save-intent
filters, and compact fact provenance. Insert also generates conversation, topic,
and project summaries from stored message text. Generated summaries are stored
separately from raw chunks and normalized facts; the conversation summary is
returned as metadata.generated_summary on search and retrieve responses.
memory_insert accepts one complete conversation object. There is intentionally
no bulk MCP insert tool. Clients may include a short metadata.summary, but
must still send the complete messages list.
Resources:
memory://conversation/example
Templates:
memory://conversation/{id}memory://search/{query}memory://timeline/{day}memory://health
Prompts:
save_conversationsearch_memoryask_memorysummarize_conversation
MCP Session Flow
Initialize:
curl -i -X POST http://127.0.0.1:8000/mcp/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {"name": "example-client", "version": "0.1.0"}
}
}'
Use the returned Mcp-Session-Id for later MCP calls:
curl -X POST http://127.0.0.1:8000/mcp/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Mcp-Session-Id: <SESSION_ID>" \
-d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'
Native Clients
Register ai-memory-hub as an MCP server in clients such as Codex, opencode,
Claude, Copilot, VS Code, or Cursor, then point the client at:
http://127.0.0.1:8000/mcp/
The same memory operations remain available through HTTP API endpoints, so agent clients and direct service clients can share one backend.
Storage Backends
The runtime uses one metadata provider and one vector provider. Select them with
providers.metadata_db and providers.vector_db. The blocks under
storage.metadata_providers and storage.vector_providers only hold settings
for possible providers; they are not active unless selected.
Multilingual Retrieval
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 in the stored conversation and the user's query.
The embedding provider, model, dimension, and relevant options form one vector space. Use the same embedding configuration for ingestion and query-time retrieval. If a persistent vector index was built with a different embedding model or provider, reindex it or use a separate vector namespace/index. Dimension checks catch many unsafe swaps, but same-dimension model changes can still corrupt ranking if mixed silently.
Changing Embedding Models For Existing Data
Use this runbook when you already have a metadata database containing your conversations and you want to switch to another embedding model.
Do not point a new embedding model at the old vector table, collection, index, or namespace. The vectors already stored there were produced in the old model's embedding space. Mixing them with new vectors corrupts ranking, and same-dimension models are not interchangeable.
- Stop
aim serveand any API, MCP, or CLI clients that can insert memory. - Back up metadata and vectors.
- Default local metadata: back up
data/metadata.sqlite3. - Default local vectors: back up
data/lancedb. - PGVector: back up the configured
storage.vector_providers.pgvector.table_name. - Hosted vector stores: take the provider's normal snapshot/export before changing collections, indexes, namespaces, or tables.
- Choose the new embedding settings and set all of them together:
providers:
embeddings: http
embedding_model: nomic-embed-text
embedding_dimension: 768
embeddings:
endpoint: http://127.0.0.1:11434/v1
- Point the new config at an empty vector destination.
- SQLite + LanceDB: keep
paths.data_dirunchanged if you want the samedata/metadata.sqlite3, but back up and replace only thedata/lancedbvector directory. Use a newpaths.data_dironly when you want a separate metadata database too. - PGVector: use a new
storage.vector_providers.pgvector.table_name, such asmemory_vectors_nomic_768. - Qdrant, Milvus, Weaviate, Redis, Typesense, MongoDB Atlas, Elasticsearch, OpenSearch, Pinecone, Turbopuffer, and Vespa: use a new collection, index, namespace, table, or schema name that contains no old-model vectors.
- Keep the same metadata database unless you intentionally want a completely separate memory store. Keeping metadata preserves conversations, facts, generated summaries, projects, users, and tokens while the vector store is rebuilt.
- Recalculate embeddings from the stored metadata:
uv run aim reindex --config new-embedding-config.yaml --json
aim reindex reads the existing conversation payloads from metadata, rebuilds
chunks, embeds them with the active embedding config, and writes vectors to the
active vector store with replacement semantics. It does not require original
transcript files or hand-written JSON files.
Useful options:
--project-id <id>reindexes one project workspace.--limit <n>reindexes only the firstnstored conversations, useful for a smoke test before a full run.--include-inactivealso recalculates vectors forpending_revieworrejectedconversations. The default only reindexes active memory.
The same reindex command is the compatibility path when enabling vector filter
pushdown for an index created before owner/project payload fields were present.
Back up the vector destination, deploy the updated provider schema or mapping,
and reindex every project whose vectors predate those fields. Until reindexing
is complete, use a fresh vector destination or a provider configuration that
reports no native filter fields; the hub will use bounded metadata-validated
fallback retrieval instead of trusting incomplete payloads. Check the active
mode with aim storage-check --json or the /health response under
vector_filtering.
- Verify the new index before removing the old one:
uv run aim storage-check --config new-embedding-config.yaml --json
uv run aim search "project memory smoke" --config new-embedding-config.yaml --top-k 5 --json
uv run aim ask "What do you remember about this project?" --config new-embedding-config.yaml --top-k 5 --json
Rollback is simple if you kept the backups: restore the old config that points at the old embedding model and old vector destination. The metadata database can stay in place when the migration only replayed duplicate conversation payloads.
providers:
metadata_db: postgres
vector_db: pgvector
storage:
metadata_providers:
postgres:
url: postgresql://user:password@127.0.0.1:5432/memory
vector_providers:
pgvector:
url: postgresql://user:password@127.0.0.1:5432/memory
table_name: memory_vectors
SQLite + LanceDB
The default local setup stores metadata in SQLite and vectors in LanceDB:
providers:
metadata_db: sqlite
vector_db: lancedb
paths:
data_dir: ./data
SQLite + Qdrant
Use Qdrant as a local Docker or Qdrant Cloud vector backend:
providers:
metadata_db: sqlite
vector_db: qdrant
storage:
vector:
allow_fallback: false
distance: cosine
vector_providers:
qdrant:
url: http://127.0.0.1:6333
api_key: ""
collection: memory_vectors
Install the optional dependency with uv sync --extra qdrant.
SQLite + Milvus
Use Milvus or Zilliz for larger vector deployments:
providers:
metadata_db: sqlite
vector_db: milvus
storage:
vector:
allow_fallback: false
distance: cosine
vector_providers:
milvus:
uri: http://127.0.0.1:19530
token: ""
collection: memory_vectors
Install the optional dependency with uv sync --extra milvus.
SQLite + Weaviate
Use Weaviate for schema-rich vector deployments:
providers:
metadata_db: sqlite
vector_db: weaviate
storage:
vector:
allow_fallback: false
vector_providers:
weaviate:
url: http://127.0.0.1:8080
api_key: ""
collection: MemoryVector
Install the optional dependency with uv sync --extra weaviate.
SQLite + Elasticsearch
Use Elasticsearch when vector storage should live in an existing Elastic cluster:
providers:
metadata_db: sqlite
vector_db: elasticsearch
storage:
vector:
allow_fallback: false
distance: cosine
vector_providers:
elasticsearch:
url: http://127.0.0.1:9200
username: ""
password: ""
index: memory_vectors
Install the optional dependency with uv sync --extra elasticsearch.
SQLite + OpenSearch
Use OpenSearch when vector storage should live in an existing OpenSearch cluster:
providers:
metadata_db: sqlite
vector_db: opensearch
storage:
vector:
allow_fallback: false
distance: cosine
vector_providers:
opensearch:
url: http://127.0.0.1:9200
username: ""
password: ""
index: memory_vectors
Install the optional dependency with uv sync --extra opensearch.
SQLite + Redis/RediSearch
Use Redis when Redis Stack already owns operational infrastructure and RediSearch should host vectors:
providers:
metadata_db: sqlite
vector_db: redis
storage:
vector:
allow_fallback: false
distance: cosine
vector_providers:
redis:
url: redis://127.0.0.1:6379/0
index: memory_vectors
key_prefix: "memory_vectors:"
Install the optional dependency with uv sync --extra redis.
SQLite + Vespa
Use Vespa when a deployed Vespa application already owns large-scale retrieval infrastructure and ai-memory-hub should feed hub-owned embeddings into it:
providers:
metadata_db: sqlite
vector_db: vespa
storage:
vector:
allow_fallback: false
distance: cosine
vector_providers:
vespa:
url: http://127.0.0.1:8080
token: ""
namespace: memory
schema: memory_vector
rank_profile: vector_similarity
Install the optional dependency with uv sync --extra vespa. Deploy the Vespa
application package and schema before starting ai-memory-hub.
SQLite + Typesense
Use Typesense when vector storage should live in a lightweight search engine with first-class filtering and faceting:
providers:
metadata_db: sqlite
vector_db: typesense
storage:
vector:
allow_fallback: false
distance: cosine
vector_providers:
typesense:
url: http://127.0.0.1:8108
api_key: ""
collection: memory_vectors
Install the optional dependency with uv sync --extra typesense.
SQLite + Pinecone
Use Pinecone when vector storage should live in hosted managed/serverless infrastructure:
providers:
metadata_db: sqlite
vector_db: pinecone
storage:
vector:
allow_fallback: false
distance: cosine
vector_providers:
pinecone:
api_key: ""
index: memory-vectors
namespace: default
cloud: aws
region: us-east-1
create_index: false
Install the optional dependency with uv sync --extra pinecone.
SQLite + Turbopuffer
Use Turbopuffer when vector storage should live in hosted object-storage-backed search infrastructure:
providers:
metadata_db: sqlite
vector_db: turbopuffer
storage:
vector:
allow_fallback: false
distance: cosine
vector_providers:
turbopuffer:
api_key: ""
namespace: memory-vectors
region: gcp-us-central1
Install the optional dependency with uv sync --extra turbopuffer.
MongoDB Metadata And Atlas Vectors
Use MongoDB for metadata when Mongo already owns application persistence, and use MongoDB Atlas Vector Search when Atlas should also own vectors:
providers:
metadata_db: mongodb
vector_db: mongodb_atlas
storage:
metadata_providers:
mongodb:
uri: mongodb://127.0.0.1:27017
database: ai_memory_hub
conversations_collection: conversations
vector_providers:
mongodb_atlas:
uri: mongodb+srv://example.mongodb.net/app
database: ai_memory_hub
collection: memory_vectors
index: memory_vector_index
Install the optional dependency with uv sync --extra mongodb.
Postgres Metadata
Use Postgres for conversation metadata:
providers:
metadata_db: postgres
vector_db: lancedb
storage:
metadata_providers:
postgres:
url: postgresql://user:password@127.0.0.1:5432/memory
PGVector
Use PGVector for vector storage:
providers:
metadata_db: postgres
vector_db: pgvector
storage:
metadata_providers:
postgres:
url: postgresql://user:password@127.0.0.1:5432/memory
vector_providers:
pgvector:
url: postgresql://user:password@127.0.0.1:5432/memory
table_name: memory_vectors
In-Memory Vectors
Use the in-memory vector backend for tests and short-lived local experiments:
providers:
vector_db: memory
Configuration
Configuration is loaded from config.yaml by default. A fuller example is
available in example.config.yaml.
providers:
embeddings: local
embedding_model: local-hash
embedding_dimension: 32
metadata_db: sqlite
vector_db: lancedb
storage:
dry_run: false
allow_trusted_appends: false
# Metadata schema compatibility allow-list. Version 1 is current.
metadata_schema_versions: [1]
vector:
allow_fallback: true
distance: cosine
vector_providers:
qdrant:
url: http://127.0.0.1:6333
api_key: ""
collection: memory_vectors
milvus:
uri: http://127.0.0.1:19530
token: ""
collection: memory_vectors
weaviate:
url: http://127.0.0.1:8080
api_key: ""
collection: MemoryVector
mongodb_atlas:
uri: ""
database: ai_memory_hub
collection: memory_vectors
index: memory_vector_index
elasticsearch:
url: http://127.0.0.1:9200
username: ""
password: ""
index: memory_vectors
opensearch:
url: http://127.0.0.1:9200
username: ""
password: ""
index: memory_vectors
redis:
url: redis://127.0.0.1:6379/0
index: memory_vectors
key_prefix: "memory_vectors:"
pinecone:
api_key: ""
index: memory-vectors
namespace: default
cloud: aws
region: us-east-1
create_index: false
turbopuffer:
api_key: ""
namespace: memory-vectors
region: gcp-us-central1
vespa:
url: http://127.0.0.1:8080
token: ""
namespace: memory
schema: memory
rank_profile: vector_similarity
typesense:
url: http://127.0.0.1:8108
api_key: ""
collection: memory_vectors
metadata_providers:
mongodb:
uri: ""
database: ai_memory_hub
conversations_collection: conversations
tokenizer:
enabled: false
encoding: cl100k_base
ask:
max_context_tokens: 2000
retrieval:
vector_score_threshold: 7.5
keyword_enabled: true
keyword_candidate_limit: 50
candidate_multiplier: 3
rank_fusion_k: 60
dense_candidate_weight: 1.0
lexical_candidate_weight: 1.0
fact_candidate_weight: 0.75
fact_candidate_limit: 25
reranker_candidate_limit: 25
reranker_timeout_seconds: 0.5
reranker_projection_text_limit: 2000
memory:
insert_policy: permissive
chunking:
strategy: message
max_tokens: 800
overlap_tokens: 80
schema:
file: ./memory/schema/conversation.schema.json
interfaces:
mcp: true
api: true
mcp:
tool_profile: advanced
paths:
data_dir: ./data
logs_dir: ./logs
embedding_endpoint:
base_url: http://localhost:11434/v1
api_key: dummy_key
max_batch_size: 128
max_batch_input_bytes: 1000000
mcp.tool_profile defaults to advanced, which exposes every current MCP tool. Set it
to simple to preview a two-tool surface containing only memory_save and
memory_ask. The save name aliases the existing memory_insert handler rather than
creating another ingestion path. This setting filters MCP tool registration only; it
does not disable HTTP endpoints or remove the specialized internal implementations
used by ask. Invalid profile names fail configuration validation.
max_batch_size and max_batch_input_bytes bound each HTTP embedding request
by input count and serialized UTF-8 JSON input-array bytes. Ingestion processes
the batches in source order and does not write any vectors until every batch
succeeds. Reduce the limits for stricter provider quotas; increase them only
within the validated configuration bounds supported by the remote endpoint.
metadata_schema_versions means "this app build supports these metadata store
schema versions." It is an array so future rolling migrations can temporarily
support old and new database layouts, for example [1, 2]. Version 1 is the
first and current metadata schema version. Startup fails if the active metadata
store reports a version outside this list.
The default chunking.strategy: message keeps one chunk per normalized message.
Set chunking.strategy: token to split long messages into token windows with
chunking.max_tokens and chunking.overlap_tokens. Token chunking is opt-in and
uses tiktoken when available, with a deterministic local heuristic fallback.
Retrieval gathers dense vector, lexical, fact, and optional graph candidate lists, then combines their positions with reciprocal rank fusion. It never subtracts lexical or metadata boosts from provider-specific raw vector scores. Exact identifiers, quoted phrases, and rare exact terms remain high-signal, followed by an optional bounded semantic reranker and deterministic metadata signals. The no-model path and all reranker timeout/error paths are deterministic. Reranker projections are size-limited, redact secrets, and omit arbitrary conversation metadata.
For migration, retrieval.keyword_weight and retrieval.metadata_weight are
still accepted so existing configuration files start unchanged, but they no
longer affect ordering. Replace keyword_weight with
lexical_candidate_weight; tune dense_candidate_weight,
fact_candidate_weight, and graph_weight only as source-list weights. Raw
score remains in responses for compatibility, while result order comes from
the fused rank.
tokenizer.encoding is an encoding name such as cl100k_base, not a model file
path. ai-memory-hub does not download tokenizer files itself. When the optional
tiktoken extra is installed, tiktoken resolves and caches the encoding data.
For persistent or offline deployments, set TIKTOKEN_CACHE_DIR to a writable
directory and prewarm the cache during setup:
TIKTOKEN_CACHE_DIR=./data/tiktoken-cache uv run python -c "import tiktoken; tiktoken.get_encoding('cl100k_base')"
Check which tokenizer path will be used:
uv run python -m memory.cli tokenizer-check --json
Containers
Build the local image:
docker build -t ai-memory-hub:local -f Containerfile .
Run the default image locally:
docker run --rm -p 127.0.0.1:8000:8000 ai-memory-hub:local
The image exposes the API and MCP service on port 8000 and starts with:
/app/.venv/bin/aim serve --host 0.0.0.0 --port 8000
The built-in container configuration uses deterministic local embeddings, SQLite
metadata, and LanceDB vectors so the image starts without external model or
database services while keeping local vector state persistent under /app/data.
Container images run as a non-root user by default and are built so OpenShift can
override the runtime UID while keeping root-group write access to /app/data,
/app/logs, and /app/.uv-cache. Use /ready for readiness probes and
/health for liveness probes.
Kubernetes probe example:
readinessProbe:
httpGet:
path: /ready
port: 8000
livenessProbe:
httpGet:
path: /health
port: 8000
For persistent local container data, mount /app/data and optionally /app/logs.
For custom configuration, mount a config file and start with:
uv run aim serve --config <path>
Keep secrets in a mounted config file or injected environment variables, not in committed images or repository files.
For a reusable Docker/Podman Compose setup that runs ai-memory-hub with Postgres metadata and PGVector vectors:
cd examples/local-stack
docker compose up --build
The example binds ai-memory-hub on host port 8000 for LAN clients. Use
http://<HOST_LAN_IP>:8000/mcp/ from another PC on the same network. It also
enables tokenizer budgeting with the optional tiktoken extra. For remote
Ollama embeddings, see examples/local-stack/config.oauth-public.yaml.
Additional checked-in provider examples are under examples/storage_providers.
They cover SQLite/LanceDB, in-memory vectors, Qdrant, MongoDB metadata,
MongoDB Atlas Vector Search, Milvus, Weaviate, Elasticsearch, OpenSearch,
Redis/RediSearch, Vespa, Typesense, Pinecone, and Turbopuffer.
Testing
Run the full local suite:
uv run pytest
Run storage tests only:
uv run pytest tests/integration/test_storage_features.py
Default local runs do not require external storage services. Live provider tests
are skipped unless their AMH_TEST_* environment variables are set. GitHub
Actions runs fake-client provider contracts in the normal CI suite and service-
backed live provider checks in .github/workflows/storage-providers.yml.
Run live Postgres and PGVector tests locally:
docker run --name aim-pgvector-test \
-e POSTGRES_USER=test \
-e POSTGRES_PASSWORD=test \
-e POSTGRES_DB=memory \
-p 5432:5432 \
-d pgvector/pgvector:pg16
export AMH_TEST_POSTGRES_DSN="postgresql://test:test@127.0.0.1:5432/memory"
uv run pytest -q tests/integration/test_storage_features.py -k "postgres_live_integration_when_dsn_provided or postgres_schema_version or pgvector_live_integration_when_dsn_provided or runtime_postgres_pgvector_live_integration_when_dsn_provided"
docker rm -f aim-pgvector-test
Benchmarks and evaluation helpers:
uv run python -m memory.benchmarks.token_budget --iterations 200
uv run python -m memory.benchmarks.retrieval_quality
uv run python -m memory.benchmarks.quality_gate --output reports/quality/quality-gate.json
uv run python -m memory.benchmarks.cache_candidates --iterations 1000
uv run python tools/run_efficiency_reports.py --output-dir reports/efficiency
The representative quality gate is credential-free in CI and also accepts optional provider/model observations for comparable reports. The efficiency report suite writes individual JSON reports and a manifest. Its GitHub Actions workflow runs weekly or by manual dispatch, not on normal pushes or pull requests, and uploads the report set with 30-day retention. Deterministic ask, ingestion, reranker, and context-selection reports share a stable work ledger with total and per-request amplification counters. Cache and token-budget reports separate cold first-call latency from warm p50/p95/p99 distributions; concurrency and quality reports use the same percentile calculation.
Container CI verifies Hadolint, image build, packaged aim serve startup,
/ready, MCP initialize at /mcp/, arbitrary non-root UID behavior, and
writable runtime paths.
A Bruno integration layer provides black-box local and CI smoke tests for the live API/MCP surface against a running server and configured metadata/vector stores. The Bruno lane uploads HTML and JUnit artifacts and publishes JUnit results through GitHub Actions test summaries. Pytest CI jobs also emit JUnit XML artifacts for unit/integration, E2E, and storage lanes.
Project Structure
memory/
api/ FastAPI application and HTTP routes
backend/ metadata stores, vector stores, redaction, dry-run wrappers
ingestion/ schema validation and ingestion agents
interfaces/ MCP server implementation
schema/ conversation JSON schema
docs/ architecture notes, plans, and improvement documents
tests/ unit, integration, and end-to-end tests
Security Considerations
- Store real API keys outside committed configuration files.
- Use secure database connection strings and network access controls.
- Treat stored conversations as sensitive application data.
- Review retention, deletion, and redaction requirements before production use.
- Add authentication before exposing the API or MCP endpoint beyond localhost.