Session & Long-Term Memory
Managing session lifecycle and persistent wisdom.
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 wisdom — durable facts, skills, and patterns that persist across all sessions. This is the compounding value.
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.
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 facts rank higher by default because they have been validated across sessions.
const context = await client.retrieveMemories({
query: 'concurrency patterns for auth',
limit: 10,
});
// Returns both session observations and long-term facts, ranked by relevanceUse contextTypes to retrieve only long-term knowledge (skill, fact, preference) or only session data (session) depending on the task.