🇶🇦 Proudly built in Qatar 🇶🇦 — make ❤️ not 🚀
Most AI agents are amnesiac by design — every conversation starts from zero. VyasaGraph changes that. It's an embedded knowledge graph that lets your agent remember people, decisions, and relationships, then find them later by meaning — not just keywords. No server to run, no infrastructure to maintain. Just drop it in and your agent goes from stateless to genuinely context-aware.
Because memory is what separates a tool from a colleague.
VyasaGraph = No more Agentic Amnesia
What gives VyasaGraph superpowers?
1. SHORT TERM MEMORY — RAM layer. Instant access to current-session context. Survives context compaction. Written before every response.
2. LONG TERM MEMORY — Hard drive layer. Permanent knowledge graph with semantic search, graph relations, and project tracking. Persists across sessions.
VyasaGraph does this all automatically. No need to tell it to do anything memory-related.
| | SESSION-STATE | VyasaGraph |
|---|---|---|
| Speed | Instant (file read) | ~5–100ms |
| Scope | Current session | All sessions |
| Purpose | Hot context, write-ahead log | Permanent knowledge |
| Survives compaction? | ✅ Yes (plain file) | ✅ Yes |
| Semantic search? | ❌ No | ✅ Yes (HNSW vectors) |
| Best for | Pending tasks, decisions in flight | People, projects, history |
works_at, reports_to, owns, etc.)
What this skill does with your data:
memory.db, SESSION-STATE.md). Nothing is sent to external servers except OpenAI embedding calls (if you set OPENAI_API_KEY).
What you should NOT store in VyasaGraph:
Memory is opt-in by design. The instructions in this skill tell the agent when to record information, but you control what data you share with your agent. The agent only stores what you tell it — it does not scrape, intercept, or auto-collect data from other sources.
Retention: SESSION-STATE.md is designed to be cleared at session end. memory.db is permanent until you delete it. To erase all memory: delete memory.db.
npm install vyasagraph
Copy the SESSION-STATE template to your workspace root:
cp node_modules/vyasagraph/SESSION-STATE-TEMPLATE.md SESSION-STATE.md
Set your OpenAI API key (for semantic embeddings — text search works without it):
# .env
OPENAI_API_KEY=sk-...
Add this to your MEMORY.md (or equivalent instruction file):
## FIRST ACTION EVERY MESSAGE — MANDATORY
1. READ `SESSION-STATE.md` for hot context from current session
2. WRITE to SESSION-STATE.md BEFORE responding if user gives new decisions, deadlines, or context
- Update "Last updated" timestamp on every write
- Clear completed tasks from Pending Actions
3. SEARCH VyasaGraph: `const results = await vg.smartSearch('topic', 5);`
4. THEN respond with loaded context
## AUTO-RECORD — EVERY CONVERSATION
When the user shares substantive information, record it in that same reply:
- New facts about people → addObservations()
- Decisions or strategies → createEntities() + addObservations()
- New relationships → createRelations()
- Status changes → updateEntity()
Rule: If the user tells you something you didn't know before, write it to VyasaGraph
in that same reply. Do not wait for end of session.
## SESSION-STATE vs VyasaGraph
- SESSION-STATE = CPU cache (hot, ephemeral, write-ahead log, session scope)
- VyasaGraph = hard drive (permanent, semantic search, cross-session knowledge)
- Both required. Neither replaces the other.
## Key Paths
- VyasaGraph DB: `./memory.db`
- SESSION-STATE: `./SESSION-STATE.md`
Add this to your SOUL.md:
## Memory System
I use a two-layer memory stack:
1. SESSION-STATE.md — working memory for the current session. I read this at the
start of every message and update it before responding with anything important.
This is how I remember what we were doing when context compresses.
2. VyasaGraph — long-term knowledge graph. Stores entities (people, projects,
decisions) with relations and semantic vector search. I search this for context
on every substantive message.
If the user tells me something I didn't know before, I write it to VyasaGraph
in that same reply. I do not defer to end-of-session.
import * as vg from 'vyasagraph/src/index.js';
// Initialize (creates memory.db if it doesn't exist)
await vg.init('memory.db');
// Store knowledge
await vg.createEntities([{
name: 'Alice (user)',
entityType: 'Person',
observations: ['Software engineer', 'Based in Berlin', 'Prefers concise answers']
}]);
// Create relationships
await vg.createRelations([{
from: 'Alice (user)',
to: 'Acme Corp',
relationType: 'works_at'
}]);
// Add facts as you learn them
await vg.addObservations([{
entityName: 'Alice (user)',
contents: ['Leading the platform redesign project', 'Deadline: end of Q2']
}]);
// Semantic search — finds by meaning, not just keywords
const results = await vg.smartSearch('software engineering Berlin', 5);
// Always close
await vg.close();
// ✅ Always use smartSearch — semantic + name boosting
const results = await vg.smartSearch('project management strategy', 10);
// Text fallback (no embeddings needed)
const found = await vg.searchText('Berlin engineer', 5);
// Open specific entities by name
const entities = await vg.openNodes(['Alice (user)', 'Bob (colleague)']);
// Full graph export
const { entities, relations } = await vg.readGraph();
// Stats
const stats = await vg.getStats();
// { entityCount: 42, relationCount: 18 }
Built-in task board — track projects with status, priority, and next actions:
await vg.createEntities([{
name: 'P01 - Website redesign',
entityType: 'Project',
observations: ['Modernise the company website'],
metadata: {
status: 'Active', // Not Started | Active | On Hold | Blocked | Complete
priority: 'High', // High | Medium | Low
category: 'Work', // Work | Personal
nextAction: 'Finalise wireframes by Friday'
}
}]);
// Update when done
await vg.updateEntity('P01 - Website redesign', {
metadata: { status: 'Complete', completedAt: new Date().toISOString() }
});
// Get formatted markdown task board
const board = await vg.formatAsVtasks();
Log recurring errors as entities — build a pattern library over time:
await vg.createVerror({
subsystem: 'cron_daily_brief',
errorType: 'timeout',
errorMessage: 'Daily brief timed out after 30s',
impact: 'User did not receive morning update'
});
// Check unresolved issues
const unresolved = await vg.getUnresolvedVerrors();
// Mark resolved
await vg.resolveVerror('ERR-123456 (cron timeout, 2025-01-15)', 'Increased timeout to 60s');
Descriptive names = better semantic search:
// Person: Name (aliases, role, relationship)
'Alice Johnson (Alice, Head of Engineering, reports to Bob)'
// Project: ID + name
'P01 - Website redesign'
// Document: Name (type, date)
'Q1 Strategy (board presentation, 2025-Q1)'
Always set entityType:
Person — individuals
Project — tracked work (with metadata)
Document — written artefacts
Analysis — analytical outputs
Communication — messages, threads
Error — verrors (auto-managed)
共 1 个版本