Memory

Memory is not one global blob. It is scoped and reviewable, so agents build durable context without polluting each other.

Scopes

Scope	Visibility
`global`	shared by all agents
`project`	shared inside one project
`agent_private`	only this agent can read/write
`task`	only available during one task/run
`user_profile`	your preferences and long-term instructions

Memory document

{
  "_id": "mem_001",
  "scope": "project",
  "project_id": "nexus",
  "agent_id": null,
  "type": "architecture_decision",
  "title": "Nexus uses MongoDB as orchestration DB",
  "content": "The user wants Nexus Core in Rust, MongoDB for state, Kubernetes isolated agents, and Taiga as first board integration.",
  "tags": ["architecture", "mongodb", "kubernetes"],
  "importance": 0.9,
  "created_at": "2026-05-30T00:00:00Z"
}

Two layers

1. Declarative memory (MongoDB) — architecture decisions, project preferences, coding conventions, deployment details, known bugs, user preferences.

2. Retrieval memory (embeddings / vector search) — past task summaries, PR summaries, error fixes, debugging history, long logs.

Both layers are live. The worker owns all vector-memory maintenance (it is the only component with MongoDB + Qdrant + embedding access; agent runner pods stay confined and receive memory pre-assembled in their run config):

Step	What happens	Where
Index	Newly-`active` declarative memories are embedded (OpenAI) and upserted into Qdrant; `embedded` flips to `true`.	`dispatch::tick` → `memory::index_pending`
Retrieve	At dispatch, the task title/description queries Qdrant for vector-similar lessons, merged on top of the declarative scope search and capped.	`dispatch::build_run_request` → `memory::retrieve`
Compact	On a slow cadence, recent run summaries (HISTORY) are distilled by a summarizer into a few durable lessons, proposed as pending memory.	compaction loop → `memory::compress_recent`

Tunables (worker env): QDRANT_URL, QDRANT_API_KEY, OPENAI_API_KEY (from the app secret), NEXUS_MEMORY_COLLECTION (default nexus_memory), NEXUS_EMBED_MODEL (default text-embedding-3-small), NEXUS_COMPACTION_INTERVAL_SECS (default 21600), NEXUS_COMPACTION_MIN_EPISODES (default 3). If the key or Qdrant endpoint is absent, retrieval degrades gracefully to MongoDB text search.

Human control: review before permanence

Do not allow agents to freely write permanent memory at the beginning. Use this flow first:

Agent proposes memory
  → Nexus stores as pending
  → You approve in UI
  → Memory becomes active

Later, auto-approve low-risk memory.

Memory page (UI)

Search memory · Filter by scope
Edit memory · Pin memory · Delete memory
Approve pending memory
View which agent created it

How memory enters a run

At dispatch, the worker searches declarative memory using the agent's read_scopes (ranked by importance + tags) and queries Qdrant for vector-similar lessons, merges and de-duplicates them, and injects the top results into the run config. After the run, proposed memory lands in the review queue unless the scope is auto-approved.

Scopes​

Memory document​

Two layers​

Human control: review before permanence​

Memory page (UI)​

How memory enters a run​

Related​