Skip to main content

​
Overview

The MubitMemoryEngine writes captured events to Mubit for semantic search, cross-contributor context sharing, and collaborative Q&A.

​
Class: MubitMemoryEngine

​
Constructor

constructor(options?: MubitMemoryOptions)
​
options.apiKey
string
Mubit API key (defaults to MUBIT_API_KEY environment variable)
​
options.endpoint
string
Mubit endpoint URL
​
options.httpEndpoint
string
HTTP-specific endpoint
​
options.grpcEndpoint
string
gRPC-specific endpoint
​
options.transport
MubitTransport
Transport protocol: "auto" | "http" | "grpc"
​
options.agentId
string
default:"codaph"
Agent identifier for Mubit runs
​
options.runIdPrefix
string
default:"codaph"
Prefix for Mubit run IDs
​
options.projectId
string
Shared project ID (overrides per-repo IDs)
​
options.actorId
string
Default actor ID for events
​
options.runScope
MubitRunScope
default:"session"
Run scope strategy:
  • "session": Separate run per session (codaph:{projectId}:{sessionId})
  • "project": Shared run across all sessions (codaph:{projectId})
​
options.enabled
boolean
default:"true"
Enable/disable memory writes
​
options.client
MubitClientLike
Custom Mubit client instance

​
Methods

​
writeEvent

Writes a single event to Mubit. 
async writeEvent(
  event: CapturedEventEnvelope
): Promise<MemoryWriteResult>
​
event
CapturedEventEnvelope
required
Event to write
​
accepted
boolean
Whether Mubit accepted the event
​
deduplicated
boolean
True if event was deduplicated by Mubit
​
jobId
string
Mubit job ID for async processing
​
raw
unknown
Raw Mubit response

​
writeEventsBatch

Writes multiple events in a single batch request. 
async writeEventsBatch(
  events: CapturedEventEnvelope[]
): Promise<void>
​
events
CapturedEventEnvelope[]
required
Events to write

​
writeRunState

Updates run state variables in Mubit. 
async writeRunState(
  runId: string,
  statePatch: Record<string, unknown>
): Promise<void>
​
runId
string
required
Mubit run ID
​
statePatch
Record<string, unknown>
required
State variables to set

​
querySemanticContext

Performs semantic search over Mubit run history. 
async querySemanticContext(
  options: MubitSemanticQueryOptions
): Promise<Record<string, unknown>>
​
options.runId
string
required
Run ID to query
​
options.query
string
required
Natural language query
​
options.limit
number
default:"8"
Maximum results to return
​
options.includeLinkedRuns
boolean
default:"false"
Include linked runs in search
​
options.directLane
'semantic_search' | 'hdql_query'
default:"hdql_query"
Query lane for direct bypass mode
​
options.mode
'agent_routed' | 'direct_bypass'
default:"direct_bypass"
Query routing mode

​
fetchContextSnapshot

Retrieves a context snapshot from Mubit. 
async fetchContextSnapshot(
  options: MubitContextSnapshotOptions
): Promise<Record<string, unknown>>
​
options.runId
string
required
Run ID
​
options.timelineLimit
number
default:"500"
Maximum timeline events to include
​
options.refresh
boolean
default:"false"
Force snapshot refresh

​
isEnabled

Checks if memory engine is enabled and configured. 
isEnabled(): boolean
Returns: true if API key is configured and enabled

​
runIdForSession

Generates Mubit run ID for a session. 
runIdForSession(repoId: string, sessionId: string): string

​
promptRunIdForRepo

Generates Mubit run ID for prompt-specific tracking. 
promptRunIdForRepo(repoId: string): string

​
Run Scope Strategies

​
Session Scope (Default)

Each captured session gets its own Mubit run: 
const engine = new MubitMemoryEngine({
  apiKey: process.env.MUBIT_API_KEY,
  runScope: 'session',
});

// Creates run: codaph:{repoId}:{sessionId}
Pros:
  • Isolated session context
  • Clear session boundaries
Cons:
  • No cross-session context sharing

​
Project Scope

All sessions for a project share a single Mubit run: 
const engine = new MubitMemoryEngine({
  apiKey: process.env.MUBIT_API_KEY,
  runScope: 'project',
  projectId: 'owner/repo',
});

// Creates run: codaph:owner/repo
Pros:
  • Shared context across all contributors and sessions
  • Better for collaborative teams
Cons:
  • Larger run history

​
Helper Functions

​
mubitRunIdForSession

function mubitRunIdForSession(
  repoId: string,
  sessionId: string,
  runIdPrefix?: string
): string

​
mubitRunIdForProject

function mubitRunIdForProject(
  repoId: string,
  runIdPrefix?: string
): string

​
createMubitMemoryFromEnv

Creates a Mubit engine from environment variables. 
function createMubitMemoryFromEnv(
  options?: Omit<MubitMemoryOptions, "apiKey">
): MubitMemoryEngine | null
Returns: Configured engine or null if MUBIT_API_KEY not set

​
Usage Example

import { MubitMemoryEngine } from './lib/memory-mubit';
import { IngestPipeline } from './lib/ingest-pipeline';
import { JsonlMirror } from './lib/mirror-jsonl';

const memory = new MubitMemoryEngine({
  apiKey: process.env.MUBIT_API_KEY,
  runScope: 'project',
  projectId: 'myorg/myrepo',
  agentId: 'codaph',
});

const mirror = new JsonlMirror('.codaph');
const pipeline = new IngestPipeline(mirror, {
  memoryEngine: memory,
  memoryWriteConcurrency: 4,
  memoryBatchSize: 20,
});

// Events are automatically written to Mubit
await pipeline.ingest('prompt.submitted', {
  prompt: 'Implement user authentication',
}, {
  source: 'codex_sdk',
  repoId: 'abc123',
  sessionId: 'session-1',
  threadId: 'thread-1',
  sequence: 1,
});

await pipeline.flush();

​
Semantic Search Example

const memory = new MubitMemoryEngine({
  apiKey: process.env.MUBIT_API_KEY,
});

const runId = memory.runIdForSession('abc123', 'session-1');

const results = await memory.querySemanticContext({
  runId,
  query: 'What authentication methods were discussed?',
  limit: 10,
  includeLinkedRuns: true,
});

console.log('Relevant context:', results);

​
Activity Streams

The engine writes activity streams to Mubit for timeline visualization:
  • Main activity stream: Compacted event envelopes
  • Prompt stream: Separate stream for prompt-specific tracking
  • Session summaries: Aggregated session metadata
  • Diff parts: File change diffs for code review context

​
Circuit Breaker

When used with IngestPipeline, Mubit writes automatically open a circuit after consecutive failures (default: 3). This prevents cascading failures while allowing local mirror writes to continue.

Build docs developers (and LLMs) love

Get started for freeTalk to us