What is 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.

Features

Quick Start

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

1. Embed the runtime into your own app

pnpm add @melandlabs/opencontext

A 30-second example of the memory API:

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

const store = await createMemoryStore({
	db: { type: "sqlite-vec", path: "./memory.db" },
	vector: { provider: "openai", model: "text-embedding-3-small" },
});

await store.raw.remember({
	content: "User prefers dark mode in all tools",
	scope: "user:42",
});

const hits = await store.searchRawMemorySemantically({
	query: "What does the user prefer?",
	userId: "u-42",
	limit: 5,
});

2. Build this monorepo from source

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

3. Run the HTTP daemon from npm

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

4. Wire the MCP server into Claude Desktop / Cursor

Add to your claude_desktop_config.json (or Cursor → Settings → MCP):

{
	"mcpServers": {
		"opencontext": {
			"command": "npx",
			"args": ["-y", "@melandlabs/opencontext", "mcp"],
			"env": {
				"DATABASE_URL": "postgres://user:pass@host:5432/opencontext"
			}
		}
	}
}

Four tools become available inside the editor: memory.health,
memory.searchUnified, memory.writeRawMessage,
memory.getRawMessage.

Examples

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.

Common usage patterns

The memory API

@melandlabs/opencontext exposes one factory and four verbs. The
verbs are the minimum set that covers the full lifecycle of a fact —
everything else is implementation. See
packages/memory-store/README.md
for the full configuration matrix and recipes.

Temporal queries (time travel)

Every node in the context graph has valid_from and valid_until
fields. A recall can ask for facts as-of a particular timestamp by
filtering valid_from ≤ t < valid_until — useful for "what did the
user believe last Tuesday?" or "which preference is current?".

const asOf = await store.recall({
	query: "user's preferred working hours",
	scope: "user:42",
	asOf: new Date("2026-08-01"),
});

MCP server

@melandlabs/opencontext exposes the same operations over
stdio — usable from Claude Desktop, Cursor, Claude Code, Codex CLI,
or any MCP-capable agent runtime. The CLI entry point is
opencontext (subcommand mcp is the default).

Cross-source search

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,
});

Backend selection

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.

Why It Is Different

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.

Provider matrix

Architecture

                       ┌────────────────────────────┐
                       │     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.

Used in production

• 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.

Documentation

• 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

Contributing

See CONTRIBUTING.md.

License

Apache-2.0. © 2026 Meland Labs.