@openweave/weave-graph

🧠 weave-graph

WeaveGraph — The knowledge graph engine at the heart of OpenWeave.

Part of the OpenWeave monorepo.

What it does

WeaveGraph manages all memory for an OpenWeave session:

• Stores concepts, decisions, errors and corrections as typed graph nodes
• Connects them with semantic edges (relates, causes, corrects, implements, depends_on)
• Compresses context into the graph when the LLM window reaches 75% capacity
• Retrieves relevant nodes from long-term memory given a query
• Persists everything to disk by chat_id, survives across sessions

Node Types

Type	Description
CONCEPT	A key idea or term in the project
DECISION	An architectural or implementation decision
MILESTONE	A planned deliverable
ERROR	A response flagged as incorrect by the user (suppressed)
CORRECTION	The correct version linked to an ERROR node
CODE_ENTITY	A function, class, or module created during the session

Edge Types

Relation	Meaning
RELATES	General semantic relationship
CAUSES	A causes B
CORRECTS	A is the correction of B (B is an ERROR node)
IMPLEMENTS	A implements B (code → decision)
DEPENDS_ON	A depends on B
BLOCKS	A blocks B

SynapticEngine — Conexiones Neuronales Retroactivas

El SynapticEngine (en desarrollo — M16) da a WeaveGraph su comportamiento neuronal. Cada nodo nuevo que entra al grafo es comparado contra toda la historia, sin importar cuándo fue creado el nodo existente.

Tres comportamientos (roadmap)

Comportamiento	Módulo	Descripción
Retroactive Linking	synaptic-engine.ts	Al insertar un nodo, descubre y crea edges con nodos históricos relevantes
Hebbian Strengthening	hebbian-weights.ts	Edges cuyos nodos son recuperados juntos aumentan su peso (+0.1)
Temporal Decay	hebbian-weights.ts	Edges inactivos se debilitan gradualmente (× 0.99 por ciclo)

Estructura de módulos (v0.8.0)

packages/weave-graph/src/
├── index.ts               ← ContextGraphManager (existente)
├── node.ts                ← NodeBuilder (existente)
├── edge.ts                ← EdgeBuilder (existente)
├── compression.ts         ← CompressionManager (existente)
├── persistence.ts         ← PersistenceManager (existente)
├── synaptic-engine.ts     ← Retroactive linking (M16 — en desarrollo)
└── hebbian-weights.ts     ← Strengthening + decay (M17 — planificado)

Umbrales por defecto

Variable de entorno	Default	Descripción
WEAVE_SYNAPSE_THRESHOLD	0.72	Similitud mínima para crear un edge retroactivo
WEAVE_SYNAPSE_MAX_CONNECTIONS	20	Máximo de edges automáticos por nodo
WEAVE_HEBBIAN_STRENGTH	0.1	Incremento de edge.weight por co-activación
WEAVE_DECAY_RATE	0.99	Factor de decay aplicado por ciclo inactivo
WEAVE_PRUNE_THRESHOLD	0.05	Weight mínimo antes de eliminar el edge

Uso (preview API)

import { SynapticEngine, ContextGraphManager, NodeBuilder } from "@openweave/weave-graph";

const graph = new ContextGraphManager("chat_abc123");
const synapse = new SynapticEngine({ threshold: 0.72, maxConnections: 20 });

// Nodo histórico (creado hace un mes, ya en el grafo)
graph.addNode(NodeBuilder.concept("TypeScript generics", "Parametric polymorphism"));

// Nodo nuevo — SynapticEngine crea automáticamente el edge retroactivo
const newNode = NodeBuilder.concept("Generic constraints en TS", "extends keyword");
const newEdges = await synapse.linkRetroactively(newNode, graph);
// → crea edge RELATES entre ambos nodos aunque el primero tenga 1 mes de antigüedad

graph.addNode(newNode);
console.log(`${newEdges.length} conexiones retroactivas creadas`);

Estado: SynapticEngine está en desarrollo activo en la rama feature/synaptic-engine. La API puede cambiar antes del release v0.8.0.

Quick Start

TypeScript / Node.js

import {
  ContextGraphManager,
  NodeBuilder,
  EdgeBuilder,
  PersistenceManager,
  NodeType,
  EdgeType,
} from "@openweave/weave-graph";

// Initialize a graph for a session
const graph = new ContextGraphManager("chat_abc123");

// Create and add nodes
const concept = NodeBuilder.concept("TypeScript", "A typed superset of JavaScript");
const decision = NodeBuilder.decision("Use TypeScript for type safety");

graph.addNode(concept);
graph.addNode(decision);

// Connect nodes with edges
const edge = EdgeBuilder.relates(concept.id, decision.id);
graph.addEdge(edge);

// Query the graph
const results = graph.queryNodesByLabel("Type");
console.log(`Found ${results.length} nodes mentioning "Type"`);

// Get graph statistics
const stats = graph.getStats();
console.log(stats);
// {
//   totalNodes: 2,
//   totalEdges: 1,
//   nodesByType: { CONCEPT: 1, DECISION: 1 },
//   edgesByType: { RELATES: 1 },
//   chatId: "chat_abc123",
//   ...
// }

// Persist the graph
const persistence = new PersistenceManager("./weave-data");
await persistence.saveGraph(graph.snapshot());

// Load a previous session
const loaded = await persistence.loadOrCreateGraph("chat_abc123");
console.log(`Loaded graph with ${loaded.getAllNodes().length} nodes`);

Available Node Types

• CONCEPT — A key idea or term
• DECISION — An architectural or implementation choice
• MILESTONE — A planned deliverable
• ERROR — A flagged incorrect response
• CORRECTION — The correct version of an ERROR
• CODE_ENTITY — A function, class, or module

Available Edge Types

• RELATES — General semantic relationship
• CAUSES — A causes B
• CORRECTS — A corrects B (A is CORRECTION, B is ERROR)
• IMPLEMENTS — A implements B (code → decision)
• DEPENDS_ON — A depends on B
• BLOCKS — A blocks B

API

ContextGraphManager

// Node operations
addNode(node: Node): Node
getNode(nodeId: string): Node | undefined
updateNode(nodeId: string, updates: Partial<Node>): Node | undefined
deleteNode(nodeId: string): boolean
getAllNodes(): Node[]

// Edge operations
addEdge(edge: Edge): Edge
getEdge(edgeId: string): Edge | undefined
updateEdge(edgeId: string, updates: Partial<Edge>): Edge | undefined
deleteEdge(edgeId: string): boolean
getAllEdges(): Edge[]
getEdgesFromNode(nodeId: string): Edge[]
getEdgesToNode(nodeId: string): Edge[]

// Queries
queryNodesByLabel(query: string): Node[]
queryNodesByType(type: NodeType): Node[]
queryEdgesByType(type: EdgeType): Edge[]

// Utilities
getStats(): GraphStats
snapshot(): GraphSnapshot
clear(): void
shouldCompress(): boolean

PersistenceManager

// File I/O
async saveGraph(snapshot: GraphSnapshot): Promise<void>
async loadGraph(chatId: string): Promise<GraphSnapshot | null>
async loadOrCreateGraph(chatId: string): Promise<ContextGraphManager>

// Session management
async graphExists(chatId: string): Promise<boolean>
async deleteGraph(chatId: string): Promise<void>
async listSessions(): Promise<SessionInfo[]>

// Configuration
setDataDir(newDataDir: string): void
getDataDir(): string

Development

# Build
npm run build

# Test
npm run test

# Watch mode
npm run dev

# Lint
npm run lint

# Clean build artifacts
npm run clean

content="Use PostgreSQL for persistence, not SQLite — project will scale",
node_type=NodeType.DECISION,
tags=["database", "architecture"]

)

Add a concept and relate it

concept = graph.add_node( content="Session persistence by chat_id", node_type=NodeType.CONCEPT ) graph.add_edge(decision.id, concept.id, EdgeType.RELATES)

Suppress an error and record correction

graph.suppress_error_node( node_id=bad_response_node.id, correction_content="Use async/await, not threading — the codebase is fully async" )

Query relevant context before responding

relevant = graph.query_relevant_nodes("database connection pooling", top_k=5)

Compress context when window is getting full

compressed_summary = graph.compress_context_to_graph( context_text=long_conversation_text, llm_extractor_fn=my_extraction_function )

## Storage

All data is persisted to:

{storage_path}/{chat_id}/ ├── context_graph.json ← Full graph (nodes + edges) ├── roadmap.md ← Human-readable milestone status ├── decisions.md ← Decision log └── errors.md ← Error pattern registry

## Installation

```bash
pip install openweave-graph
# or within the monorepo:
pnpm --filter weave-graph dev