npm package: @jcmrs/opencode-vmem
Description: Persistent memory plugin for AI agents with episodic, semantic, and procedural memory
Author: jcmrs
Latest version: 1.1.0

# @jcmrs/opencode-vmem

[![npm version](https://badge.fury.io/js/@jcmrs%2Fopencode-vmem.svg)](https://www.npmjs.com/package/@jcmrs/opencode-vmem)
[![CI](https://github.com/jcmrs/opencode-vmem/actions/workflows/ci.yml/badge.svg)](https://github.com/jcmrs/opencode-vmem/actions/workflows/ci.yml)

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

```bash
npm install @jcmrs/opencode-vmem
```

Or install directly from GitHub:

```bash
npm install jcmrs/opencode-vmem
```

## Quick Start

```typescript
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](docs/commands.md) for detailed command documentation.

## Configuration

Create `.opencode/vmem.json` in your project:

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

See [docs/configuration.md](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

```bash
# 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