Memongo

MongoDB-native Company Brain memory framework for AI apps, agents, and teams.

Quickstart · Framework · Architecture · API · Live Site · Benchmarks · Release Gate

Memongo gives AI systems durable Company Brain memory on top of MongoDB. It stores conversations, facts, procedures, knowledge-base chunks, episodes, and graph relationships in one MongoDB-backed memory engine, then retrieves context with vector search, full-text search, and hybrid ranking.

The public repo is intentionally focused: a runnable API, MCP server, TypeScript client, AI SDK tools, web console, docs, Docker MongoDB setup, and release checks.

Version 2.2.0 is available on npm, as verified downloadable packages, and as an API container. See the release notes for scope and limitations.

Quickstart

Prerequisites:

• Node.js and Bun versions specified by engines.node and packageManager in package.json
• Docker (for the local MongoDB path — uses MongoDB Atlas Local Preview with mongot for Atlas Search)
• MongoDB 8.3 or later with Search index management and Automated Embedding. Memongo refuses to start on anything less, and says which requirement is unmet. See the deployment contract.
• A MongoDB replica set or sharded cluster. Memongo writes use transactions, which a standalone mongod does not support; writes then fail with ADD_FAILED. Atlas clusters and the Docker stack below (a single-node replica set) qualify. To use your own standalone server, convert it to a replica set.

git clone https://github.com/romiluz13/memongo.git
cd memongo
bun install
bun run build

The API imports the workspace packages from their built dist/ output, so build once after installing and again after pulling changes.

Start MongoDB:

docker compose -f docker/docker-compose.yml up -d
export MEMONGO_MONGODB_URI="mongodb://127.0.0.1:27017/?directConnection=true"
export MEMONGO_API_KEY="local-dev-secret"
# Required for semantic search results below (Atlas Model API key, `al-...` prefix):
export VOYAGE_API_KEY="al-your-atlas-model-api-key"

The default Docker file uses MongoDB Atlas Local Preview, pinned by digest. Set VOYAGE_API_KEY to a MongoDB Atlas Model API key with the al-... prefix: every vector index uses MongoDB auto-embeddings.

MongoDB Automated Embedding is an upstream Preview feature. Review its deployment requirements and current limitations when configuring your environment.

Start the API:

cd apps/api
bun run dev

In another shell, add and search memory:

curl -s http://127.0.0.1:3847/health

curl -s http://127.0.0.1:3847/v1/add \
  -H "content-type: application/json" \
  -H "authorization: Bearer $MEMONGO_API_KEY" \
  -d '{"content":"The user prefers TypeScript and concise release notes.","sessionId":"demo-user"}'

curl -s http://127.0.0.1:3847/v1/search \
  -H "content-type: application/json" \
  -H "authorization: Bearer $MEMONGO_API_KEY" \
  -d '{"query":"What does the user prefer?","sessionKey":"demo-user","maxResults":5}'

Semantic search needs VOYAGE_API_KEY (see above) to match stored memories by meaning. A search that cannot embed its query fails with a typed error; it never answers with an empty list. To check a deployment before starting the API, run bun run --filter @memongo/api preflight.

For a guided setup, see Quickstart.

What You Get

Surface	Location	Purpose
HTTP API	apps/api	Hono server exposing /v1/*, /health, and OpenAPI
MCP server	apps/mcp	stdio adapter for MCP-compatible clients
Web console	apps/web	Operator UI for the API
Docs	apps/docs	Public docs
Engine	packages/memory-engine	MongoDB memory core
Bridge	packages/memory-bridge	Stable facade over the engine
Client SDK	packages/client	TypeScript HTTP client
AI tools	packages/tools	Vercel AI SDK tool helpers
Published barrel	packages/memongo-memory	@memongo/memory convenience package

Memory Framework

Memongo's framework contract is:

• Memory taxonomy: episodic events, semantic facts, procedural playbooks, profile preferences, workspace knowledge, and provenance.
• Core operations: recall, context bundles, remember, update, forget, feedback, and trace.
• Scope model: session, user, agent, workspace, tenant, and global.
• Safety model: read by default; write only on explicit user, app, operator, test, or import intent.

See Memory Framework, Memory Taxonomy, and Company Brain Guide.

How It Works

App / Agent / MCP client
  -> Memongo HTTP API or TypeScript client
  -> Memory bridge
  -> MongoDB memory engine
  -> MongoDB Search, Vector Search, collections, indexes, and telemetry

Memongo keeps the product interface small while the engine handles:

• Conversation and event memory
• Structured facts and revisions
• Procedure memory
• Knowledge-base ingestion
• Episodes and graph relationships
• Hybrid retrieval across vector and lexical evidence
• Optional high-recall retrieval profiles for evaluation and audit work

Configuration

Memongo reads environment variables and an optional config file at ~/.memongo/memongo.json.

Common variables:

Variable	Purpose
MEMONGO_MONGODB_URI	MongoDB connection string
MEMONGO_API_HOST	API bind host, default 127.0.0.1
MEMONGO_API_PORT	API port, default 3847
MEMONGO_API_KEY	Recommended bearer token for API requests
MEMONGO_AGENT_ID	Default memory isolation key
MEMONGO_SHARED_CLIENT	Set 0 (or false/no/off) to opt out of the default shared-client runtime and restore per-agent clients; default on
MEMONGO_MANAGER_CACHE_MAX	Manager cache LRU cap, default 50
MEMONGO_MANAGER_CACHE_IDLE_TTL_MS	Idle managers evicted after this long, default 600000 (10 min)
MEMONGO_JOB_SWEEP_MS	Standing memory-job sweep interval, default 30000 (writes still drain immediately)
MEMONGO_MONGODB_RECALL_PROFILE	latency, balanced, or proof; default balanced
MEMONGO_MONGODB_FUSION_METHOD	scoreFusion or rankFusion; default scoreFusion. Any other value, including the removed js-merge, fails boot
MEMONGO_QUERY_EMBEDDING_MODEL	Compatible Voyage 4 query model; default voyage-4-large
VOYAGE_API_KEY	Atlas Model API key for MongoDB auto-embed lanes
MEMONGO_ENRICHMENT_BASE_URL	Optional OpenAI-compatible or Anthropic endpoint for LLM enrichment
MEMONGO_ENRICHMENT_API_KEY	API key for the enrichment endpoint
MEMONGO_ENRICHMENT_MODEL	Model used by enrichment when enabled

Deployment-safe defaults: all memory managers for the same MongoDB URI share one client (and therefore one bounded connection pool, maxPoolSize 10) and the manager cache is LRU-capped with idle eviction in every mode, so agent count no longer multiplies connections — connections are fixed per URI, and standing poll traffic is capped by the bounded manager cache (<=50 sweeps per 30 s). Per-agent clients return with MEMONGO_SHARED_CLIENT=0; note that in that mode an idle agent re-bootstraps its manager (and reconnects) after the idle TTL, and per-agent pool settings apply per manager again.

OpenAI-compatible enrichment defaults to Authorization: Bearer. Gateways that require provider-specific headers can set MEMONGO_ENRICHMENT_AUTH_STYLE=api-key or x-api-key; gateways that require newer completion token naming can set MEMONGO_ENRICHMENT_TOKEN_PARAM=max_completion_tokens.

For managed Atlas and Atlas Local Preview notes, see Configuration and Self-hosting.

Benchmarks

In a complete 500-question LongMemEval retrieval run, Memongo returned every scenario successfully and achieved:

Metric	Result
Official session RecallAny@10	98.57%
Official session RecallAll@10	94.75%
Internal R@5	93.15%
Internal R@10	97.16%
Internal hit rate	98.94%

The run used a build from before M2 with MongoDB-native $scoreFusion, Voyage 4 Large query embeddings, Voyage rerank-2.5, and no generative LLM enrichment. The current release has no rerank stage, so the run does not describe it. These are retrieval metrics, not generated-answer accuracy. The registered release contract still classifies the run as not publishable because its 1,244 ms p95 exceeded the 1,000 ms gate and build, cost, and native-operation evidence was incomplete.

Competitor headline numbers use different evaluators and units. Mem0 and Zep publish generated-answer accuracy, Supermemory publishes a differently aggregated Recall@15 result, and Letta's public 74.0% result is on LoCoMo. None is an apples-to-apples comparison with Memongo's retrieval-only result.

Read the methodology, competitor context, and failed gates before quoting any number: Benchmark Evidence.

Benchmark rules:

• No question-ID tuning.
• No hidden fallback.
• Retrieval recall and judged answer quality are reported separately.
• No broad ecosystem leadership claim is made from one benchmark family.

Release Gate

Run these checks before publishing packages, tagging a release, or making production claims:

bun install --frozen-lockfile
bun run check-types
bun run lint
bun run build
bun run test
bun run check-publishability

Live validation requires a running API and MongoDB:

bun run proof-pack
bun run agent-smoke

See Production-ready Checklist, Validation Pack, and Publishing.

Packages

npm install @memongo/memory
npm install @memongo/client
npm install @memongo/tools

Package READMEs:

• @memongo/client
• @memongo/tools
• @memongo/memory
• @memongo/memory-bridge
• @memongo/memory-engine

License

Apache-2.0. See LICENSE.