OpenContext

OpenContext is the context runtime layer that sits underneath an agentic application. It is not a UI, a chat surface, or a model provider — it is the glue between the things that make an agent useful: durable memory, retrieval, context correction, multi-platform connectivity, scheduled awareness, and the embedding-shaped persistence that holds all of it together.

→ Read docs/architecture.md for the full data model, the lifecycle of a fact, and the transport surface map.

There are four ways to get opencontext into your project. Pick the one that matches what you're building.

pnpm add @melandlabs/opencontext

A 30-second example of the memory API:

import { createMemoryStore, getRawMessageManager } from "@melandlabs/opencontext";

// The store defaults to SQLite at MEMORY_STORE_DB_PATH (./memory.db by
// default). Each call returns an awaitable handle.
const store = await createMemoryStore();
const messages = await getRawMessageManager();

// A message is one fact: a single piece of content attributed to a user.
// `messageId` makes the call idempotent across re-ingest.
const now = Date.now();
await messages.storeMessages([
	{
		messageId: "msg-1",
		userId: "u-42",
		content: "User prefers dark mode in all tools",
		platform: "test",
		botId: "bot-1",
		timestamp: now,
		createdAt: now,
	},
]);

// Unified search fans out to memory + insights + knowledge. Sources you
// haven't wired up just emit a warning — fine for a single-backend deploy.
const hits = await store.searchUnifiedMemory({
	userId: "u-42",
	query: "What does the user prefer?",
	limit: 5,
});
// hits.count    — number of results
// hits.sources  — which sub-indexes were actually consulted
// hits.warnings — per-source degradation (e.g. missing embedder)

git clone https://github.com/melandlabs/opencontext.git
cd opencontext
pnpm install
pnpm -r build

# After `pnpm add -g @melandlabs/opencontext`, the bin is on PATH:
opencontext http \
  --embedding-provider local \
  --memory-backend sqlite-vec \
  --host 127.0.0.1 --port 7421
# Or, without a global install, via npx:
npx -y @melandlabs/opencontext http \
  --embedding-provider local --memory-backend sqlite-vec
curl http://127.0.0.1:7421/health

opencontext mcp \
  --embedding-provider local \
  --memory-backend sqlite-vec

The examples/ workspace ships a runnable example per capability area. Clone, install, and run:

git clone https://github.com/melandlabs/opencontext.git
cd opencontext/examples
pnpm install
pnpm test

See examples/README.md for the full walkthrough.

@melandlabs/opencontext exposes two factory calls plus a small, flat search surface. Writes go through the raw-message manager and remain idempotent on messageId; reads fan out to memory + insights + knowledge and degrade gracefully when a source is unconfigured. See packages/memory-store/README.md for the full configuration matrix and recipes.

Every fact in the underlying context graph carries valid_from and valid_until, so an as-of query is "the facts whose validity interval covered t". The unified search API does not expose point-in-time filtering directly — temporal access lives one layer deeper, in @melandlabs/ai/memory-consolidation (graph-aware-query) and @melandlabs/indexeddb/memory-graph-evolution. See those packages for as-of recall.

@melandlabs/opencontext exposes the same operations over stdio — usable from Claude Desktop, Cursor, Claude Code, Codex CLI, or any MCP-capable agent runtime.

createUnifiedSearch(deps) lets you wire per-source searchers independently. Sources you omit just emit a warning — fine for a read-only deployment or a single-backend stack:

import { createUnifiedSearch } from "@melandlabs/opencontext";

const search = createUnifiedSearch({
	embedQuery: myEmbedder.embedQuery,
	searchRawMessagesAnn: pgAnnSearch,
	searchInsights: insightIndex.search,
	searchKnowledge: ragIndex.search,
});

const { results, warnings } = await search.searchUnifiedMemory({
	userId: "u-1",
	query: "what changed since yesterday?",
	sources: ["memory", "insights", "knowledge"],
	limit: 10,
});

Every backend is selected at boot via MemoryStoreConfig — no abstraction hides what each one can do. Mixing backends is supported: you can keep raw messages in Postgres while using Chroma as the vector index, for example.

OpenContext is not a memory library and not a vector DB. It is a runtime substrate — the @melandlabs/opencontext package bundles contracts, memory-store, retrieval primitives, the loop engine, and the agent runtime behind one dependency.

                       ┌────────────────────────────┐
                       │     Host application       │   ← your UI, CLI, or daemon
                       │   (a reference app,        │
                       │    or your own embedder)   │
                       └─────────────┬──────────────┘
                                     │
            ┌────────────────────────┴────────────────────────┐
            │   @melandlabs/opencontext                       │
            │   contracts · memory · rag · loop · agent       │
            └────────────────────────┬────────────────────────┘
                                     │
       ┌─────────────────────────────┴─────────────────────────────┐
       │   Storage backends                                        │
       │   sqlite-vec · postgres · indexeddb · chroma · pgvector   │
       └─────────────────────────────┬─────────────────────────────┘
                                     │
       ┌─────────────────────────────┴─────────────────────────────┐
       │   Integrations mesh  (gmail, slack, …)                    │
       └───────────────────────────────────────────────────────────┘

Full data-flow diagrams, transport surfaces, and storage backends are in docs/architecture.md.

• OpenLoomi — a cross-platform desktop "Attention Agent" built on top of OpenContext. See the OpenLoomi README for how the same primitives wire up into a real product.

• docs/architecture.md — data model, lifecycle, data plane and control plane
• docs/philosophy.md — why this shape
• Each package's README.md — API surface, examples, migration notes

See CONTRIBUTING.md.

Apache-2.0. © 2026 Meland Labs.