@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