Session & Long-Term Memory
Managing session lifecycle and durable structured agent knowledge.
Two Tiers of Knowledge
LocusGraph operates on two tiers:
- Session memory — ephemeral events tied to a single session. Useful for tracking what happened, but not all of it needs to persist.
- Long-term knowledge — durable facts, patterns, and skills that persist across all sessions. This is the compounding value.
Memory is recall. Long-term knowledge is understanding. The job of the session lifecycle is to graduate the right session events into long-term knowledge.
Session Lifecycle
1. Start
Create a session context with a unique identifier.
const sessionId = `session:${Date.now().toString(36)}`;2. Observe
Store events tagged with the session context as work progresses.
await client.storeEvent({
graph_id: 'default',
event_kind: 'observation',
context_id: 'session:2025_03_19',
payload: { topic: 'debugging', value: 'Found race condition in auth middleware' },
});3. Summarize and Graduate
At session end, extract durable knowledge and store it under permanent contexts. Use extends to link the new knowledge back to the session it came from.
await client.storeEvent({
graph_id: 'default',
event_kind: 'fact',
context_id: 'skill:concurrency',
extends: ['session:2025_03_19'],
payload: { topic: 'race_condition_fix', value: 'Use mutex guards around shared auth state' },
});The session observation stays in the graph for traceability. The graduated fact lives under skill:concurrency and surfaces in future retrievals about concurrency — regardless of session.
Not every session event deserves graduation. Store session events generously, but graduate only the knowledge that will matter next week. That is what keeps the structured agent knowledge layer dense and high-signal.
What Graduates
| Session Event | Graduates To |
|---|---|
| "Found race condition in auth" | skill:concurrency — "Use mutex guards around shared auth state" |
| "User prefers verbose logging" | preference:logging — "Enable verbose logging by default" |
| "Retry logic fixed timeout issue" | skill:error_handling — "Exponential backoff with 3s base for this API" |
Retrieval Across Tiers
Retrieve from both tiers in a single query. Long-term knowledge ranks higher by default because it has been validated across sessions.
const context = await client.retrieveMemories({
query: 'concurrency patterns for auth',
limit: 10,
});
// Returns both session observations and long-term knowledge, ranked by relevance and confidenceUse contextTypes to retrieve only long-term knowledge (skill, fact, preference) or only session data (session) depending on the task.