@jcmrs/opencode-vmem

@jcmrs/opencode-vmem

A portable, persistent memory plugin for AI/LLM/Agent contexts. Provides episodic, semantic, and procedural memory capabilities.

Features

• Episodic Memory - Captures and stores observations from tool executions
• Semantic Memory - Extracts and stores facts, preferences, and profiles
• Procedural Memory - Learns workflows and suggests relevant procedures
• Semantic Search - Embedding-based similarity search with hybrid fallback
• Context Injection - Builds relevant context for AI sessions
• Export & Archive - Export to JSON/Markdown, archive old memories

Installation

npm install @jcmrs/opencode-vmem

Or install directly from GitHub:

npm install jcmrs/opencode-vmem

Quick Start

import { Mind } from '@jcmrs/opencode-vmem';

const mind = await Mind.open('/path/to/project');

await mind.observe({
  type: 'tool_execution',
  content: 'User prefers TypeScript over JavaScript',
  tool: 'bash'
});

const results = await mind.search('typescript preferences', 5);
console.log(results);

Tools (Agent-Callable)

Tool	Description
mind_search	Search memories by query
mind_state	Get memory system statistics
mind_forget	Mark a memory for deletion
mind_add_card	Add a memory card
mind_context	Build current memory context
mind_suggest	Get procedure suggestions

Commands (User-Callable)

Command	Description
/mind:stats	Display memory statistics
/mind:search <query>	Search memories
/mind:context	Show current context
/mind:forget <id>	Mark memory for deletion
/mind:add <entity> <slot> <value>	Add memory card
/mind:cards	List all memory cards
/mind:export	Export memory (json/md/plain)
/mind:archive	Archive current memory
/mind:help	Show help

See docs/commands.md for detailed command documentation.

Configuration

Create .opencode/vmem.json in your project:

{
  "capture": {
    "enabled": true,
    "minOutputLength": 50
  },
  "embedding": {
    "enabled": true,
    "model": "Xenova/nomic-embed-text-v1"
  },
  "context": {
    "maxTokens": 3000,
    "format": "markdown"
  }
}

See docs/configuration.md for all options.

Architecture

.opencode/
├── memory/
│   ├── mind.mv2        # Main memory store (MV2 format)
│   ├── cards.json      # Memory cards (extracted facts)
│   ├── procedures.json # Learned procedures
│   └── tombstones.json # Soft-deleted frames
├── archives/           # Archived memories
└── vmem.json           # Configuration

Memory Types

Episodic (Observations)

Raw events captured from tool executions:

• Tool inputs and outputs
• User interactions
• Session context

Semantic (Memory Cards)

Extracted knowledge:

• fact - Verified information
• preference - User preferences
• profile - User/Project profiles
• goal - Stated objectives

Procedural (Workflows)

Learned patterns:

• State-Action-Result tuples
• Workflow templates
• Success/failure rates

Search Modes

Mode	Description
lex	Lexical search (exact words)
sem	Semantic search (embeddings)
auto	Hybrid (tries semantic, falls back to lexical)

Development

# Clone and install
git clone https://github.com/jcmrs/opencode-vmem.git
cd opencode-vmem
npm install

# Run tests
npm test

# Run smoke test
npm run smoke

# Build
npm run build

# Validate real-world usage
npm run validate

CI/CD

This project uses GitHub Actions for:

• Multi-platform testing (Ubuntu, Windows, macOS)
• Node.js 18 and 20 support
• Automated smoke tests
• Coverage reporting

License

MIT