oc-mnemoria 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 one-bit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,292 @@
+# oc-mnemoria
+
+[![CI](https://github.com/one-bit/oc-mnemoria/actions/workflows/ci.yml/badge.svg)](https://github.com/one-bit/oc-mnemoria/actions/workflows/ci.yml)
+
+Persistent shared memory for [OpenCode](https://opencode.ai) agents, powered
+by [mnemoria](https://crates.io/crates/mnemoria).
+
+## What it does
+
+Every time you start a new OpenCode session, your AI assistant loses all
+context from previous conversations. oc-mnemoria fixes this by giving all
+agents a shared "hive mind" — a single persistent memory store where every
+agent can read and write.
+
+Each memory entry is tagged with the agent that created it (plan, build, ask,
+review, ...) so any agent can tell who recorded what. The build agent can see
+what the plan agent decided; the review agent can recall bugs the build agent
+fixed. No context is lost between roles.
+
+Memories are stored locally in an append-only binary file using
+[mnemoria](https://github.com/one-bit/mnemoria) — a Rust engine with hybrid
+BM25 + semantic search, CRC32 checksum chains, and corruption recovery.
+
+## Prerequisites
+
+- [Rust toolchain](https://rustup.rs/) (to install the mnemoria CLI)
+- [OpenCode](https://opencode.ai/) (v0.1+)
+- Node.js >= 18
+
+## Installation
+
+### 1. Install the mnemoria CLI
+
+```sh
+cargo install mnemoria
+```
+
+### 2. Add the plugin to your project
+
+Add `oc-mnemoria` to the `plugin` array in your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["oc-mnemoria"]
+}
+```
+
+Or use the install script:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/one-bit/oc-mnemoria/main/install.sh | bash
+```
+
+### 3. Install slash commands (optional)
+
+Copy the `commands/` directory to your OpenCode config:
+
+```sh
+cp commands/*.md ~/.config/opencode/commands/
+```
+
+## How it works
+
+### Storage layout
+
+All agents share a single memory store:
+
+```
+.opencode/mnemoria/
+  log.bin           # append-only binary log
+  manifest.json     # metadata and checksums
+  mnemoria.lock     # advisory file lock
+```
+
+You can interact with the store directly using the `mnemoria` CLI:
+
+```sh
+mnemoria --path .opencode stats
+mnemoria --path .opencode search "authentication"
+mnemoria --path .opencode export memories.json
+```
+
+### Agent tagging
+
+Every memory entry is tagged with the agent that created it via mnemoria's
+native `--agent` flag. The agent name is a first-class field on each entry,
+visible in search results, timeline output, and JSON exports.
+
+```sh
+# Search only the build agent's memories
+mnemoria --path .opencode search -a build "authentication"
+
+# Show only the plan agent's timeline
+mnemoria --path .opencode timeline -a plan
+```
+
+### Automatic capture
+
+The plugin automatically captures context from tool usage:
+
+| Tool   | What gets stored                          |
+|--------|-------------------------------------------|
+| `read` | File paths, function names, line counts   |
+| `bash` | Commands run, success/failure, file paths |
+| `edit` | Files modified, type of change            |
+| `write`| Files created                             |
+| `grep` | Search patterns, result counts            |
+| `glob` | Search patterns, matched files            |
+
+Each observation is linked to the user's intent (extracted from the
+conversation) via chain IDs, so any agent can trace *why* something was done.
+
+### System prompt injection
+
+At the start of each session, recent observations and past user goals are
+injected into the system prompt. Each entry shows which agent created it,
+giving the current agent immediate cross-agent context.
+
+## Tools
+
+| Tool            | Description                                         |
+|-----------------|-----------------------------------------------------|
+| `remember`      | Store a categorized observation in shared memory     |
+| `search_memory` | Search by keyword/semantic similarity               |
+| `ask_memory`    | Ask a natural language question                     |
+| `memory_stats`  | View statistics for the shared store                |
+| `timeline`      | Browse memories chronologically (all agents)        |
+
+### Entry types
+
+Observations are categorized when stored:
+
+`intent` `discovery` `decision` `problem` `solution` `pattern` `warning`
+`success` `refactor` `bugfix` `feature`
+
+## Slash commands
+
+| Command              | Description                          |
+|----------------------|--------------------------------------|
+| `/memory ask <q>`    | Ask about past decisions             |
+| `/memory search <q>` | Search memories                      |
+| `/memory stats`      | Show memory statistics               |
+| `/memory recent`     | Show recent memories                 |
+| `/memory timeline`   | Chronological view                   |
+
+## Inspecting memories from the command line
+
+You can use the `mnemoria` CLI directly to browse, search, and manage the
+memory store outside of OpenCode. All commands use `--path .opencode` to
+point at your project's store (mnemoria auto-appends `mnemoria/` to resolve
+the actual data directory).
+
+### Browse the timeline
+
+```sh
+# Most recent 20 entries (newest first)
+mnemoria --path .opencode timeline -r
+
+# Last 5 entries
+mnemoria --path .opencode timeline -r -l 5
+
+# Only entries from the build agent
+mnemoria --path .opencode timeline -a build
+
+# Entries from a specific time range (Unix ms timestamps)
+mnemoria --path .opencode timeline -s 1700000000000 -u 1700100000000
+```
+
+Output looks like:
+
+```
+Timeline (3 entries):
+1. [discovery] (build) Found async pattern in auth module - 1700000100000
+2. [decision] (plan) Use JWT for session tokens - 1700000050000
+3. [intent] (plan) Fix authentication flow - 1700000000000
+```
+
+### Search memories
+
+```sh
+# Keyword + semantic hybrid search
+mnemoria --path .opencode search "authentication"
+
+# Limit results
+mnemoria --path .opencode search "error handling" -l 5
+
+# Search only one agent's memories
+mnemoria --path .opencode search -a review "security"
+```
+
+### Ask a question
+
+```sh
+# Ask a natural language question against the memory store
+mnemoria --path .opencode ask "What decisions were made about the database schema?"
+
+# Scoped to a single agent
+mnemoria --path .opencode ask -a plan "What was the original plan for auth?"
+```
+
+### View statistics
+
+```sh
+mnemoria --path .opencode stats
+```
+
+```
+Memory Statistics:
+  Total entries: 42
+  File size: 4096 bytes
+  Oldest entry: 1700000000000
+  Newest entry: 1700001000000
+```
+
+### Export to JSON
+
+```sh
+mnemoria --path .opencode export memories.json
+```
+
+This produces a JSON array with full entry data including `agent_name`,
+`entry_type`, `summary`, `content`, `timestamp`, and checksum fields.
+Useful for scripting, analysis, or migrating data.
+
+### Add a memory manually
+
+```sh
+mnemoria --path .opencode add \
+  -a build \
+  -t decision \
+  -s "Switched from REST to GraphQL" \
+  "After benchmarking, GraphQL reduced payload size by 60%"
+```
+
+The `-t` flag accepts any entry type: `intent`, `discovery`, `decision`,
+`problem`, `solution`, `pattern`, `warning`, `success`, `refactor`,
+`bugfix`, `feature`. Defaults to `discovery` if omitted.
+
+### Verify store integrity
+
+```sh
+mnemoria --path .opencode verify
+```
+
+Checks the CRC32 checksum chain across all entries. Returns a non-zero exit
+code on corruption, making it suitable for CI or pre-commit hooks.
+
+## Git integration
+
+Mnemoria's append-only binary format is designed for version control. You
+can commit the memory store to track history alongside your code:
+
+```sh
+git add .opencode/
+git commit -m "update agent memories"
+```
+
+Or ignore it:
+
+```sh
+echo ".opencode/mnemoria/" >> .gitignore  # ignore just the memory store
+```
+
+## FAQ
+
+**How much disk space does this use?**
+The store starts empty. A typical entry is ~100-500 bytes. Active daily use
+produces roughly 2-10 MB per year.
+
+**Is my data sent anywhere?**
+No. Everything stays on your local filesystem. The mnemoria engine runs
+entirely offline.
+
+**How fast is it?**
+The mnemoria Rust engine delivers sub-millisecond search latency for
+typical store sizes (<10k entries). The plugin shells out to the CLI, so
+there's ~50ms overhead per operation from process spawning.
+
+**Can I reset the memory?**
+Delete the store directory:
+```sh
+rm -rf .opencode/mnemoria/
+```
+
+**Can I search only one agent's memories?**
+Yes. Pass the `agent` parameter to `search_memory`, `ask_memory`, or
+`timeline`. From the CLI: `mnemoria --path .opencode search -a build "auth"`.
+
+## License
+
+MIT

package/commands/ask.md

@@ -0,0 +1,7 @@
+---
+description: Ask about past decisions
+agent: build
+---
+Ask my memory: "$ARGUMENTS"
+
+Use the ask_memory tool to get an answer based on our past sessions. If no relevant memories are found, let me know.

package/commands/recent.md

@@ -0,0 +1,7 @@
+---
+description: Show recent memories
+agent: build
+---
+Show me the recent memories from our previous sessions. Use the timeline tool with limit=10 and reverse=true to show the most recent 10 memories.
+
+Each entry shows which agent created it.

package/commands/search.md

@@ -0,0 +1,7 @@
+---
+description: Search memories
+agent: build
+---
+Search my memory for $ARGUMENTS. Use the search_memory tool to find relevant past context.
+
+Provide a clear summary of what you found, including the score and type of each memory.

package/commands/stats.md

@@ -0,0 +1,8 @@
+---
+description: Show memory statistics
+agent: build
+---
+Show me the memory statistics. Use the memory_stats tool to display:
+- Total number of entries stored
+- Memory file size
+- Date range of memories (oldest and newest)

package/commands/timeline.md

@@ -0,0 +1,7 @@
+---
+description: Show memories in chronological order
+agent: build
+---
+Show me the timeline of memories from our previous sessions. Use the timeline tool to display memories in chronological order.
+
+By default, show the most recent 20 memories (newest first). Each entry shows which agent created it.

package/dist/index.d.ts

@@ -0,0 +1,300 @@
+import { Plugin } from '@opencode-ai/plugin';
+
+/**
+ * oc-mnemoria — OpenCode Plugin
+ *
+ * Persistent shared memory ("hive mind") for OpenCode agents, powered by
+ * the mnemoria Rust engine (v0.3.1+). All agents share a single memory
+ * store — each entry is tagged with the agent that created it via
+ * mnemoria's native --agent flag.
+ */
+
+declare const OcMnemoria: Plugin;
+
+/**
+ * Types for oc-mnemoria — aligned with the mnemoria Rust crate.
+ */
+/**
+ * Memory entry types matching mnemoria's EntryType enum.
+ */
+type EntryType = "intent" | "discovery" | "decision" | "problem" | "solution" | "pattern" | "warning" | "success" | "refactor" | "bugfix" | "feature";
+/**
+ * A memory entry as returned by the mnemoria CLI (JSON output).
+ */
+interface MemoryEntry {
+    id: string;
+    agent_name: string;
+    entry_type: EntryType;
+    summary: string;
+    content: string;
+    timestamp: number;
+    checksum: number;
+    prev_checksum: number;
+}
+/**
+ * A search result from mnemoria.
+ */
+interface SearchResult {
+    id: string;
+    entry: MemoryEntry;
+    score: number;
+}
+/**
+ * Statistics about a memory store.
+ */
+interface MemoryStats {
+    total_entries: number;
+    file_size_bytes: number;
+    oldest_timestamp: number | null;
+    newest_timestamp: number | null;
+}
+/**
+ * Options for timeline queries.
+ */
+interface TimelineOptions {
+    limit: number;
+    since?: number;
+    until?: number;
+    reverse: boolean;
+}
+/**
+ * Known opencode agent types. Extensible — any string is accepted.
+ */
+type AgentName = "plan" | "build" | "ask" | "review" | (string & {});
+/**
+ * Configuration for the plugin.
+ */
+interface PluginConfig {
+    /** Parent directory passed to `mnemoria --path`. The CLI appends `mnemoria/` automatically. Default: ".opencode" */
+    memoryDir: string;
+    /** Maximum context observations injected into the system prompt. Default: 20 */
+    maxContextObservations: number;
+    /** Maximum token budget for context injection. Default: 2000 */
+    maxContextTokens: number;
+    /** Enable debug logging. Default: false */
+    debug: boolean;
+}
+declare const DEFAULT_CONFIG: PluginConfig;
+/**
+ * Observation stored through the plugin (enriched with plugin-level metadata).
+ */
+interface Observation {
+    id: string;
+    type: EntryType;
+    summary: string;
+    content: string;
+    timestamp: number;
+    /** The tool that produced this observation */
+    tool?: string;
+    /** The agent that owns this memory */
+    agent?: AgentName;
+    /** Metadata for chain linking */
+    chainId?: string;
+    parentId?: string;
+    metadata?: ObservationMetadata;
+}
+interface ObservationMetadata {
+    callId?: string;
+    filePaths?: string[];
+    findings?: string[];
+    patterns?: string[];
+    sessionId?: string;
+    userGoal?: string;
+}
+/**
+ * What gets returned from extracting a user's intent.
+ */
+interface UserIntent {
+    goal: string;
+    context: string[];
+    filePaths: string[];
+}
+
+/**
+ * Mind — shared hive-mind memory manager.
+ *
+ * All agents share a single mnemoria store at `.opencode/mnemoria/`. Each
+ * memory entry is tagged with the agent that created it via mnemoria's
+ * native `--agent` flag, so agents can see each other's memories while
+ * still knowing who recorded what.
+ */
+
+declare class Mind {
+    private cli;
+    private currentChainId;
+    private currentParentId;
+    private config;
+    private constructor();
+    /**
+     * Open (or create) the shared hive-mind store.
+     */
+    static open(config?: Partial<PluginConfig>): Promise<Mind>;
+    /** The current intent chain ID. */
+    getCurrentChainId(): string | null;
+    /** The path to the memory store. */
+    getMemoryPath(): string;
+    /**
+     * Store a new observation, tagged with the agent that created it.
+     */
+    remember(input: {
+        type: EntryType;
+        summary: string;
+        content: string;
+        agent: AgentName;
+        tool?: string;
+        metadata?: ObservationMetadata;
+    }): Promise<string>;
+    /**
+     * Store an observation linked to the current intent chain.
+     */
+    rememberWithContext(input: {
+        type: EntryType;
+        summary: string;
+        content: string;
+        agent: AgentName;
+        tool?: string;
+        metadata?: ObservationMetadata;
+    }): Promise<string>;
+    /**
+     * Set the user's intent for this conversation turn.
+     * Creates a new chain ID that links subsequent observations.
+     */
+    setIntent(message: string, extractedGoal: string, agent: AgentName): Promise<string>;
+    /**
+     * Search the shared memory. Optionally filter by agent.
+     */
+    search(query: string, limit?: number, agent?: AgentName): Promise<SearchResult[]>;
+    /**
+     * Ask a question against the shared memory. Optionally filter by agent.
+     */
+    ask(question: string, agent?: AgentName): Promise<string>;
+    /**
+     * Get a timeline of memories. Optionally filter by agent.
+     */
+    timeline(options?: Partial<TimelineOptions>, agent?: AgentName): Promise<Observation[]>;
+    /**
+     * Get memory statistics for the shared store.
+     */
+    stats(): Promise<MemoryStats>;
+    /**
+     * Build context for system prompt injection.
+     * Returns recent observations capped by token budget.
+     */
+    getContext(query?: string): Promise<{
+        recentObservations: Observation[];
+        relevantMemories: SearchResult[];
+        tokenCount: number;
+    }>;
+}
+/**
+ * Get or create the shared Mind instance.
+ * All agents share this single instance (and single mnemoria store).
+ */
+declare function getMind(config?: Partial<PluginConfig>): Promise<Mind>;
+/**
+ * Reset the shared Mind singleton (for testing).
+ */
+declare function resetMind(): void;
+
+/**
+ * Wrapper around the `mnemoria` CLI binary (v0.3.1+).
+ *
+ * All interaction with the Rust mnemoria engine goes through this module.
+ * Each method shells out to the `mnemoria` binary, parses the output, and
+ * returns typed results.
+ */
+
+/**
+ * MnemoriaCli — stateless wrapper for a single mnemoria store directory.
+ *
+ * `basePath` is the **parent** directory. The CLI appends `mnemoria/` when
+ * the path is a directory, so the actual store lives at `basePath/mnemoria/`.
+ */
+declare class MnemoriaCli {
+    readonly basePath: string;
+    constructor(basePath: string);
+    /** Check whether the mnemoria binary is available on PATH. */
+    static isAvailable(): Promise<boolean>;
+    /** Path to the actual store directory (basePath/mnemoria/). */
+    get storePath(): string;
+    /** Whether the store has been initialised. */
+    isInitialized(): boolean;
+    /** Initialise a new memory store. Idempotent if already initialised. */
+    init(): Promise<void>;
+    /** Ensure the store exists (init if needed) and return this instance. */
+    ensureReady(): Promise<this>;
+    /**
+     * Add a memory entry. Returns the entry ID.
+     *
+     * `agent` is required by mnemoria v0.3.1+.
+     */
+    add(entryType: EntryType, summary: string, content: string, agent: string): Promise<string>;
+    /**
+     * Search memories. Returns parsed results.
+     *
+     * Output format (v0.3.1):
+     *   Found N results:
+     *   1. [type] (agent) summary (score: 0.123)
+     */
+    search(query: string, limit?: number, agent?: string): Promise<SearchResult[]>;
+    /**
+     * Ask a question. Returns the text answer.
+     */
+    ask(question: string, agent?: string): Promise<string>;
+    /**
+     * Get memory statistics.
+     *
+     * Output format:
+     *   Memory Statistics:
+     *     Total entries: 5
+     *     File size: 450 bytes
+     *     Oldest entry: 1771178444990
+     *     Newest entry: 1771178445123
+     */
+    stats(): Promise<MemoryStats>;
+    /**
+     * Get timeline entries.
+     *
+     * Output format (v0.3.1):
+     *   Timeline (N entries):
+     *   1. [type] (agent) summary - timestamp
+     */
+    timeline(options?: Partial<TimelineOptions>, agent?: string): Promise<MemoryEntry[]>;
+    /**
+     * Export all entries as JSON. Uses a temp file and reads it back.
+     * This is the only reliable way to get full entry data with IDs.
+     */
+    exportAll(): Promise<MemoryEntry[]>;
+    /**
+     * Verify the checksum chain integrity.
+     */
+    verify(): Promise<boolean>;
+}
+
+/**
+ * Utility functions for oc-mnemoria.
+ *
+ * Extraction, classification, and text helpers used by the plugin hooks.
+ */
+
+/** Generate a random 16-character hex ID. */
+declare function generateId(): string;
+/** Rough token estimate: ~4 chars per token. */
+declare function estimateTokens(text: string): number;
+/** Truncate text to fit within a token budget. */
+declare function truncateToTokens(text: string, maxTokens: number): string;
+interface ExtractedInfo {
+    summary: string;
+    content: string;
+    filePaths: string[];
+    findings: string[];
+    patterns: string[];
+}
+/** Extract key information from tool output based on the tool name. */
+declare function extractKeyInfo(toolName: string, output: string, args?: Record<string, unknown>): ExtractedInfo;
+/** Classify a tool's output into an observation type. */
+declare function classifyObservationType(toolName: string, output: string): EntryType;
+/** Extract the user's intent from their message. */
+declare function extractUserIntent(message: string): UserIntent;
+
+export { type AgentName, DEFAULT_CONFIG, type EntryType, type MemoryEntry, type MemoryStats, Mind, MnemoriaCli, type Observation, type ObservationMetadata, OcMnemoria, type PluginConfig, type SearchResult, type TimelineOptions, type UserIntent, classifyObservationType, OcMnemoria as default, estimateTokens, extractKeyInfo, extractUserIntent, generateId, getMind, resetMind, truncateToTokens };