You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: packages/memory/README.md
+85-2Lines changed: 85 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,8 +6,12 @@ Memory management plugin for OpenCode that enables semantic search and persisten
6
6
7
7
-**Semantic Memory Search** - Store and retrieve project memories using vector embeddings
8
8
-**Multiple Memory Scopes** - Categorize memories as convention, decision, or context
9
-
-**Automatic Deduplication** - Prevents duplicate memories from being stored
10
-
-**Session Context** - Tracks session state and injects relevant memories during compaction
9
+
-**Automatic Deduplication** - Prevents duplicates via exact match and semantic similarity detection
10
+
-**Compaction Context Injection** - Injects planning state, conventions, and decisions into session compaction for seamless continuity
11
+
-**Bundled Agents** - Ships with Code, Architect, and Memory agents preconfigured for memory-aware workflows
12
+
-**CLI Export/Import** - Export and import memories as JSON or Markdown for backup and migration
13
+
-**Dimension Mismatch Detection** - Detects embedding model changes and guides recovery via reindex
14
+
-**Session Planning** - Tracks objectives, phases, findings, and errors across sessions with automatic TTL cleanup
11
15
12
16
## Tools
13
17
@@ -20,9 +24,76 @@ Memory management plugin for OpenCode that enables semantic search and persisten
20
24
|`memory-health`| Health check or full reindex of the memory store |
21
25
|`memory-planning-update`| Update session planning state (phases, objectives, progress) |
22
26
|`memory-planning-get`| Get the current planning state for a session |
27
+
|`memory-plan-execute`| Create a new Code session and send an approved plan as the first prompt |
23
28
24
29
Planning state differs from memories: it stores temporary session data (objectives, phase progress, findings, errors) with a 7-day TTL, while memories are persisted indefinitely and retrieved via semantic search.
25
30
31
+
## Agents
32
+
33
+
The plugin bundles three agents that integrate with the memory system:
34
+
35
+
| Agent | ID | Mode | Description |
36
+
|-------|----|------|-------------|
37
+
|**Code**|`ocm-code`| primary | Primary coding agent with memory awareness. Checks memory before unfamiliar code, stores architectural decisions and conventions as it works. |
38
+
|**Architect**|`ocm-architect`| primary | Read-only planning agent. Researches the codebase, checks memory for conventions and decisions, designs implementation plans, then hands off to Code via `memory-plan-execute`. |
39
+
|**Memory**|`ocm-memory`| subagent | Expert agent for storing, retrieving, and curating project knowledge. Handles post-compaction memory extraction and contradiction resolution. |
40
+
41
+
The Architect agent operates in read-only mode (`temperature: 0.0`, all edits denied). After the user approves a plan, it calls `memory-plan-execute` to create a new Code session with the full plan as context.
42
+
43
+
## CLI
44
+
45
+
Export and import memories using the bundled CLI tool. The CLI auto-detects the project ID from git and resolves the database path automatically.
46
+
47
+
### Export
48
+
49
+
```bash
50
+
# Export all memories as JSON (stdout)
51
+
bun run src/cli/export.ts export
52
+
53
+
# Export as Markdown to file
54
+
bun run src/cli/export.ts export --format markdown --output memories.md
55
+
56
+
# Export with project and scope filter
57
+
bun run src/cli/export.ts export --project my-project --scope convention
58
+
59
+
# Limit and paginate results
60
+
bun run src/cli/export.ts export --limit 50 --offset 100
61
+
```
62
+
63
+
**Export options:**
64
+
65
+
| Flag | Description |
66
+
|------|-------------|
67
+
|`--format, -f`| Output format: `json` or `markdown` (default: `json`) |
68
+
|`--output, -o`| Output file path (prints to stdout if omitted) |
69
+
|`--project, -p`| Project ID filter (auto-detected from git) |
70
+
|`--scope, -s`| Filter by scope: `convention`, `decision`, or `context`|
71
+
|`--limit, -l`| Max number of memories (default: `1000`) |
72
+
|`--offset`| Pagination offset (default: `0`) |
73
+
|`--db-path`| Custom database file path |
74
+
75
+
### Import
76
+
77
+
```bash
78
+
# Import from JSON
79
+
bun run src/cli/export.ts import memories.json --project my-project
80
+
81
+
# Import from Markdown (format auto-detected from extension)
82
+
bun run src/cli/export.ts import memories.md --project my-project
83
+
84
+
# Skip duplicate detection
85
+
bun run src/cli/export.ts import memories.json --project my-project --force
86
+
```
87
+
88
+
**Import options:**
89
+
90
+
| Flag | Description |
91
+
|------|-------------|
92
+
|`--format, -f`| Input format: `json` or `markdown` (auto-detected from extension) |
93
+
|`--project, -p`| Project ID to assign memories to (auto-detected from git) |
94
+
|`--force`| Skip duplicate detection and import all |
95
+
|`--db-path`| Custom database file path |
96
+
26
97
## Installation
27
98
28
99
Install the package from npm:
@@ -63,6 +134,12 @@ You can edit this file to customize settings. The file is created only if it doe
description: 'Primary coding agent with awareness of project memory and conventions',
8
8
mode: 'primary',
9
+
tools: {
10
+
exclude: ['memory-plan-execute'],
11
+
},
9
12
systemPrompt: `You are a coding agent with access to a persistent memory system that stores project conventions, architectural decisions, and contextual knowledge across sessions.
0 commit comments