Knowledge Graph and Memory Management
Relevant source files
The following files were used as context for generating this wiki page:
Knowledge management in the OpenCode Swarm project is a multi-tiered system designed to capture, persist, and inject lessons learned across agent sessions. It distinguishes between short-term project context and long-term durable facts, using a dual-tier storage architecture composed of "Swarm" (project-specific) and "Hive" (cross-project) knowledge.
The system automates the lifecycle of memory from raw observations in activity logs to structured knowledge entries, and finally into compiled skills. This process ensures that agents do not "re-learn" mistakes and maintain architectural consistency across the project lifecycle.
Architecture and Memory Tiers
The project utilizes two primary tiers of knowledge storage, both persisted as JSONL (JSON Lines) files for efficient appending and parsing.
| Tier | Scope | Storage Location | Description |
|---|---|---|---|
| Swarm | Project-level | .swarm/knowledge.jsonl | Captured lessons, decisions, and patterns specific to the current repository. |
| Hive | Global-level | shared-learnings.jsonl | Mature, high-confidence knowledge promoted for use across different projects. |
Sources: src/tools/knowledge-query.ts:100-115, src/hooks/knowledge-injector.ts:15-30
Knowledge Entry Schema
Entries within the knowledge graph follow a standardized schema to facilitate relevance scoring and automated injection.
- Lesson: A concise text description of the fact or constraint (max 280 characters).
- Category: Classifications such as
architecture,security,testing, orperformance. - Confidence: A numerical score (0.0 to 1.0) representing the maturity of the knowledge.
- Status: Lifecycle states including
candidate,established,promoted, andarchived. - Metadata: Includes unique IDs (UUID v4), project names, and confirmed phase numbers.
Sources: src/hooks/knowledge-migrator.ts:250-275, src/tools/knowledge-query.ts:25-45
Knowledge Acquisition and Migration
Knowledge enters the system through three primary pathways: manual entry, curator observations, and automated migration from legacy context files.
Context Migration
The KnowledgeMigrator performs a one-time migration from .swarm/context.md to the structured .jsonl format. It parses specific Markdown sections such as "Lessons Learned," "Patterns," and "Decisions," extracting bullet points as raw migration entries.
The diagram shows the transformation of unstructured project notes into structured knowledge records.
Sources: src/hooks/knowledge-migrator.ts:120-160, src/hooks/knowledge-migrator.ts:210-240
Deduplication and Validation
To prevent redundancy, the system employs a deduplication threshold (defaulting to 0.6). It checks for "near-duplicates" using normalized text comparison before committing new entries to the store.
Sources: src/hooks/knowledge-migrator.ts:140-150, tests/unit/knowledge/relevance-scoring-task3-4.test.ts:40-50
Retrieval and Injection
Knowledge is dynamically injected into an agent's system prompt at the start of a phase via the KnowledgeInjector and SystemEnhancer hooks.
Relevance Scoring Algorithm
Retrieval is governed by a composite scoring algorithm that ranks entries based on three weighted factors:
| Factor | Weight | Logic |
|---|---|---|
| Category | 40% | Full match with current phase = 1.0; 'process' category = 0.5. |
| Confidence | 35% | Direct use of the entry's confidence score (0.0-1.0). |
| Keywords | 25% | Calculated via tag overlap with the project's tech stack and task description. |
If final scores are within a 0.001 margin, the system uses recency as a tiebreaker.
Sources: tests/unit/knowledge/relevance-scoring-task3-4.test.ts:70-100, tests/unit/knowledge/relevance-scoring-task3-4.test.ts:450-480
Injection workflow
The KnowledgeInjector constructs a compact block of lessons, respecting a strict character budget (BACM-style) to prevent prompt overflow.
This sequence ensures the Architect receives only the most relevant, high-confidence constraints for the immediate task.
Sources: src/hooks/knowledge-injector.ts:250-300, src/hooks/knowledge-injector.ts:400-430
Skill Generation
Mature, high-confidence knowledge entries are clustered and compiled into SKILL.md files. This converts durable facts into actionable procedures for agents.
Clustering Logic
The SkillGenerator uses Jaccard-based fuzzy tag clustering with a similarity threshold of 0.5. It groups entries with high tag overlap into single "KnowledgeClusters."
Sources: src/services/skill-generator.ts:120-150
Compiled Skill Structure
Generated skills include specific sections derived from knowledge metadata:
- Triggers: Conditions under which the skill applies.
- Required Procedure: Actionable steps from
required_actions. - Forbidden Shortcuts: Negative constraints from
forbidden_actions. - Delegation Template: A snippet for agents to use when delegating tasks affected by this skill.
Sources: src/services/skill-generator.ts:215-260
Research and SME Caching
The SME (Subject Matter Expert) agent maintains a specialized memory cache in .swarm/context.md under the ## Research Sources section.
- Lookup: Before performing fresh research, the SME checks the cache for the requested URL or topic.
- TTL/Staleness: SME agents flag results as
STALE_RISKif they approach their time-to-live limit. - Cache Update: New findings are appended as
CACHE-UPDATElines, which the Architect persists to the context file.
Sources: src/agents/sme.ts:115-135
Summary
The memory management system in opencode-swarm ensures architectural integrity by formalizing the transition of data from session-specific events to global "Hive" knowledge and skill-based procedures. By combining weighted relevance scoring, automated migration, and structured skill generation, the system provides a robust framework for long-term agent learning and consistent execution.