Agent Memory#
Every Nebula agent has access to persistent memory — a searchable knowledge base that survives across sessions and conversations. Memory is stored in the database (not the filesystem) and indexed with BM25 full-text search.
Memory Types#
| Type | Purpose | Example |
|---|---|---|
| user | Facts about users the agent works with | "Prefers TypeScript, senior backend engineer" |
| feedback | Behavioral guidance from past corrections | "Don't mock the database in integration tests" |
| project | Ongoing work context, decisions, deadlines | "Auth rewrite driven by compliance, due March 15" |
| reference | Pointers to external resources | "Pipeline bugs tracked in Linear project INGEST" |
Scope and Access Control#
Memory access depends on the execution context. This prevents task-stack executions from writing memories that could conflict with the agent's own knowledge.
| Execution Context | Writes to | Reads from |
|---|---|---|
| Main conversation | Agent memory | Agent memory |
| Project conversation | Project memory | Agent memory (read-only) + Project memory |
| Task stack (branch work) | Rejected | Agent memory (read-only) + Project memory (read-only) |
Managing Memory#
Open an agent's settings and navigate to the Memory tab to view, create, edit, and delete memories.
Memory editor
Each memory has:
- Title — short identifier (boosted 3x in search ranking)
- Description — one-line summary used for progressive disclosure in the system prompt
- Content — full body of the memory
How Search Works#
Memory search uses title-boosted BM25 ranking. When an agent needs to recall information:
- Tokenizes the search query
- Runs BM25 against all memories in scope
- Boosts title matches 3x over body matches
- Returns top results with relevant snippets
Memory titles and descriptions are injected into the system prompt via progressive disclosure — the agent sees a compact index of what it knows (~60 chars per concept) and can search for full content when needed.
External Knowledge Base Fan-out#
Memory search can fan out to linked external knowledge bases configured through project integration links:
- Confluence
- Notion
- YouTrack
Local results are always returned immediately. External queries run in parallel with a 5-second timeout — if an external KB is slow or unreachable, the agent still gets its local memories without delay.
Writing Memory#
Agents write memories through the nebula-memory built-in skill, which provides curl-based operations for search, read, create, update, and delete. The skill content varies by context — task-stack executions receive a read-only version.
Tip: Good memories are specific and actionable. "The auth service uses JWT with 15-min access tokens" is more useful than "learned about auth today."