opencontext

What is OpenContext?

OpenContext is the agentic context runtime that sits underneath an agentic application — and the substrate you build your own agent on top of. 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 a deterministic loop engine, all behind one dependency.

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

Who is it for?

OpenContext fits teams who need to engineer their context — that is, teams whose day-to-day work runs straight into the problems OpenContext was built to solve. Each bullet spells out the pain and how OpenContext addresses it:

• Software engineering teams. Decisions scatter across GitHub PRs, Linear tickets, Slack threads, and Notion docs — across people, tools, and quarters. New hires ask "why did we pick X?" and no one can answer. OpenContext's temporal graph stores every fact with valid_from / valid_until, so "what did we believe last quarter?" is a real, citable query — not a guess.
• Efficiency / productivity engineering teams. The people building internal automation for the rest of the company. They don't want another SaaS — they want a runtime they can drop into a CLI, an MCP server, or a daemon. OpenContext is library-first, and the deterministic Loop engine only invokes the LLM when there is real work, so it does not become a token-burning always-on loop.
• Office-assistant products. Assistants that live inside Telegram, iMessage, WhatsApp, Lark/Feishu, and friends. Same agent code, same context across channels. IntegrationRecord hides credentials, rate-limits, and reconnect logic, while platform + messageId is the natural audit trail for personal and work data.
• Financial trading teams. Every order, rebalance, and risk decision needs to be traceable and auditable. The temporal graph plus append-only corrections mean "what was the strategy in April?" is a queryable fact, not a buried guess — and the trail lines up with MiFID II / SEC retention rules.
• Legal, healthcare and other audited domains. Law firms, hospitals, and similar teams where every judgement needs per-fact provenance, append-only corrections, and exportable compliance evidence.
• Multi-agent and autonomous-workflow authors. Need scheduled, deterministic wake-up instead of an LLM loop all the way down. packages/loop ships exactly that separation.

Features

Benchmarks

Third-party memory and long-context recall benchmarks (numbers current as of 2026-08):

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, 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.search({
	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)

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 \
  --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

4. Wire the MCP server into Claude Desktop / Cursor

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

5. Use with DeepSeek Harness (DSH)

OpenContext is available as a DSH plugin that gives any DSH agent durable memory and retrieval-augmented context:

# Install the plugin from npm
dsh plugin --profile web add dsh-opencontext

# Confirm it's mounted
dsh --profile web --dump-config | grep dsh-opencontext
#   ... should contain `id: dsh-opencontext`

# Start DSH web and verify
dsh web
#   Visit http://127.0.0.1:3080/plugins and confirm dsh-opencontext shows "Enabled"

The plugin exposes 16 oc_* tools (e.g., oc_search, oc_remember, oc_memory_list) and automatically:

• Runs a recall waterfall on each turn to inject relevant historical context
• Captures user messages into durable memory
• Summarizes sessions at natural breakpoints (opt-in)

See plugins/dsh-opencontext/README.md for configuration options and the full tool reference.

6. Diagnose the install

opencontext doctor             # human-readable health checks
opencontext doctor --json      # CI-friendly { ok, exit, results } envelope
opencontext doctor --section memory-store

doctor is read-only and exits 0 on a healthy install. It scans nine sections (runtime, filesystem, loop, memory-store, embedding, policies, audit, security, integrations) and reports pass / warn / fail for each. No auto-fix in v1.

Next: Tutorials — get started, user guide, developer guide, advanced patterns, and best practices

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.

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.

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

Tutorials (Start Here)

• docs/tutorials/README.md — Tutorial index and learning path
• docs/tutorials/00-getting-started.md — Get up and running in 5 minutes
• docs/tutorials/01-user-guide.md — Understand the four verbs and temporal memory
• docs/tutorials/02-developer-guide.md — Integrate OpenContext into your app
• docs/tutorials/03-advanced-usage.md — Production patterns and advanced features
• docs/tutorials/04-best-practices.md — Tips and common pitfalls
• docs/tutorials/use-cases/README.md — Real-world use cases: personal assistant, support agent, research tracker

Architecture & Design

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