OpenCode Historian

Persistent memory for OpenCode agents, powered by QMD.

Historian helps your agent remember decisions, preferences, learnings, and project context across sessions. It stores memories as markdown, indexes them with QMD, and exposes tools for remembering, recalling, forgetting, and syncing memory.

What You Get

• Persistent memory across conversations
• Semantic search over saved memories
• Built-in memory types for decisions, issues, learnings, and preferences
• Markdown-based storage in your repo
• A bundled historian agent and memory tools
• Bundled mnemonics and heuristics skills for better agent memory workflows
• Optional Serena MCP support for code navigation

Prerequisites

• Bun 1.3.9+
• QMD installed globally
• MarkItDown optional, for better document extraction with the heuristics skill

Install QMD:

npm install -g qmd
# or
bun install -g qmd

Optional: install MarkItDown if you want heuristics to convert PDFs, Office documents, HTML, and other document formats before storing memories:

pip install markitdown

If MarkItDown is not installed, heuristics can still use LLM extraction or other available tools as a fallback.

Install the Plugin

Add the plugin to your opencode.json:

{
  "plugins": ["opencode-historian"]
}

That is enough to register the plugin, the bundled historian agent, and the memory tools.

Install the Skills

The plugin also includes skills that teach agents how to use Historian well:

• mnemonics - memory management guidance for @historian
• heuristics - source-to-memory ingestion for files and folders

Recommended install:

npx skills add https://github.com/5kahoisaac/opencode-historian/tree/main/src --skill mnemonics
npx skills add https://github.com/5kahoisaac/opencode-historian/tree/main/src --skill heuristics

After installing them:

• agents can load mnemonics for guidance on memory types, when to use @historian, and how to store or recall project knowledge correctly
• agents can load heuristics when you want to ingest documents, screenshots, notes, code, or mixed source folders into memories

Quick Start

Once the plugin is enabled, talk to the historian agent in natural language.

Save information

"Remember that we're using PostgreSQL for the database"

"Save this: we decided on JWT tokens with 24-hour expiry"

"Note that the API rate limit is 100 requests per minute"

Recall information

"What did we decide about authentication?"

"Do we have any known issues?"

"What are my preferences for this project?"

Ingest files or folders

Use the heuristics skill when you want the agent to turn existing source files into memories:

"Use heuristics to ingest ./docs into historian memories"

"Use heuristics on ./research and only save architectural decisions and issues"

"Use heuristics to extract these screenshots into memory: ./notes/*.png"

The skill takes inspiration from the useful part of the "Karpathy LLM Wiki" idea: ingest source material into a durable knowledge base. Instead of adding a separate wiki system, it keeps Historian's existing qmd-backed memory model as the source of truth.

The skill checks available memory types first, extracts content from each file, classifies durable knowledge, and saves it through @historian. It can use markitdown for documents when available, vision MCPs for images, and LLM extraction as a fallback.

Historian will:

• classify memories by type
• tag them for retrieval
• index them for semantic search
• keep them in a git-friendly markdown format

Memory Types

Historian ships with these built-in memory types:

| Type | Use For | |--------------------------|-----------------------------| | architectural-decision | System architecture choices | | design-decision | UI/UX decisions | | learning | Lessons and discoveries | | user-preference | User preferences | | project-preference | Team conventions | | issue | Known problems | | context | General context (default) | | recurring-pattern | Reusable patterns | | conventions-pattern | Coding standards |

Configuration

Optional config file:

.opencode/opencode-historian.json

Example:

{
  "appendPrompt": "Focus on API design decisions.",
  "memoryTypes": [
    {
      "name": "api-endpoint",
      "description": "API endpoint decisions"
    }
  ],
  "disabledMcps": [
    "serena"
  ]
}

Options

| Option | Default | Description | |----------------|---------|---------------------------------------------------------------------------| | model | - | Model used by the historian agent | | temperature | 0.3 | Response creativity | | appendPrompt | - | Additional instructions appended to the historian prompt | | memoryTypes | - | Custom memory types to add alongside the built-ins | | autoCompound | true | Automatically merge new learnings into existing memories when appropriate | | disabledMcps | - | Bundled MCPs to disable, for example ["serena"] |

Storage

Memories are stored as markdown files under .mnemonics/ in your project root:

.mnemonics/
├── architectural-decision/
├── design-decision/
├── learning/
└── ...

Benefits:

• human-readable
• easy to version with git
• easy to inspect or edit manually

Included Tools

The plugin registers these memory tools:

• memory_remember
• memory_recall
• memory_forget
• memory_list_types
• memory_sync

When to Use the Skill vs. the Tools

• Use the plugin to make memory available inside OpenCode
• Use the mnemonics skill to teach agents how to use @historian well
• Use the heuristics skill to convert existing files or folders into historian memories
• Use the memory tools when you want direct programmatic memory operations

In short: the plugin gives you capability, and the skills give agents better judgment about how to use it.

License

This project is licensed under the MIT License.