Skip to content

README.md

Latest commit

 

History

History
183 lines (138 loc) · 5.95 KB

README.md

File metadata and controls

183 lines (138 loc) · 5.95 KB
Raw

MemoryLayer OpenCode Plugin

Persistent memory for OpenCode sessions. Gives your AI coding agent long-term memory that survives context compaction and persists across sessions.

What It Does

This plugin integrates MemoryLayer into OpenCode via two mechanisms:

  1. MCP Tools (25 default / 38 in full) — The MemoryLayer MCP server gives the LLM direct access to remember, recall, reflect, manage sessions, drive the context sandbox / RLM, and work with chat threads, skills, and MCP-server registry entries.

  2. Proactive Hooks — The plugin automatically:

    • Injects workspace briefing and user directives at session start
    • Recalls relevant memories when you ask preference/convention questions
    • Captures tool observations (file edits, searches, commands) as working memory
    • Commits working memory before context compaction
    • Cleans up sessions on exit

Quick Start

1. Install the MemoryLayer server

pip install memorylayer-server
memorylayer serve

Or with Docker:

docker run -d -p 61001:61001 -v memorylayer-data:/data scitrera/memorylayer-server

2. Configure OpenCode

Add to your opencode.json:

{
  "mcp": {
    "memorylayer": {
      "type": "local",
      "command": ["npx", "@scitrera/memorylayer-mcp-server"],
      "environment": {
        "MEMORYLAYER_URL": "{env:MEMORYLAYER_URL}",
        "MEMORYLAYER_API_KEY": "{env:MEMORYLAYER_API_KEY}"
      },
      "enabled": true
    }
  },
  "plugin": ["@scitrera/memorylayer-opencode-plugin"]
}

3. Set environment variables (optional)

export MEMORYLAYER_URL=http://localhost:61001  # default
export MEMORYLAYER_API_KEY=your-key            # optional, for authenticated servers

4. Verify

Start OpenCode and run /memorylayer-status to check the connection.

Slash Commands

Command Description
/memorylayer-remember <content> Store a memory with auto-detected type and importance
/memorylayer-recall <query> Search memories by semantic query
/memorylayer-status Check connection status and workspace info
/memorylayer-setup Guided setup and verification

How Hooks Work

Session Start (experimental.chat.system.transform)

On first interaction, starts a server session and injects one bounded deterministic context pack. If the server does not expose context packs, the plugin falls back to the briefing/directive/sandbox requests.

User Messages (chat.message)

Detects 5 pattern categories in user messages and performs targeted recall:

  • Preference: "which X should we use", "what's our convention"
  • Recall: "remember", "what did we", "remind me"
  • Analysis: "review", "analyze", "status"
  • Implementation: "implement", "build", "fix"
  • Error: "error", "bug", "broken"

Tool Execution (tool.execute.before / tool.execute.after)

  • Before: Injects recalled context for edit/write and task/delegation tools
  • After: Silently captures observations (files, facts, concepts, intent) as working memory

Context Compaction (experimental.session.compacting)

When OpenCode supplies transcript or message data, uploads only bytes after the last acknowledged boundary as idempotent raw checkpoints. It then commits working memory and checkpoints server-side sandbox state. Retries are bounded and failures are diagnostic only, so MemoryLayer cannot indefinitely block host compaction.

Shell Environment (shell.env)

Propagates MEMORYLAYER_URL and MEMORYLAYER_API_KEY to shell commands.

Configuration

Environment Variables

Variable Default Description
MEMORYLAYER_URL http://localhost:61001 MemoryLayer server URL
MEMORYLAYER_API_KEY — API key (optional for local servers)
MEMORYLAYER_WORKSPACE_ID auto-detected Workspace identifier (auto-detected from git repo name)

Workspace Auto-Detection

The workspace ID is automatically detected from:

  1. Git remote origin repository name
  2. Git root directory name
  3. Current working directory name

Override with the MEMORYLAYER_WORKSPACE_ID environment variable.

Memory Types

Type Description Importance
semantic Facts, concepts, knowledge 0.5-0.9
procedural How-to, solutions, patterns 0.5-0.8
episodic Events, what happened 0.5-0.7
working Current task context (auto-expires) 0.3-0.6

Common Subtypes

directive, decision, fix, solution, code_pattern, error, workflow, preference, problem

Architecture

OpenCode
├── MCP Server (@scitrera/memorylayer-mcp-server)
│   └── 25 memory tools by default (38 in `full` profile)
│
├── Plugin Hooks (@scitrera/memorylayer-opencode-plugin)
│   ├── system.transform  → session briefing injection
│   ├── chat.message      → pattern-based recall
│   ├── tool.before       → pre-tool context injection
│   ├── tool.after        → observation capture
│   ├── session.compacting → working memory commit
│   └── shell.env         → env var propagation
│
└── MemoryLayer Server (memorylayer-server)
    ├── Memory storage (SQLite + vector search)
    ├── Knowledge graph (associations)
    ├── Working memory (sessions)
    └── Context sandbox (Python execution)

Troubleshooting

Server not reachable

# Check if server is running
curl http://localhost:61001/health

# Start the server
memorylayer serve

# Or with Docker
docker run -d -p 61001:61001 -v memorylayer-data:/data scitrera/memorylayer-server

MCP tools not available

Verify opencode.json has the mcp.memorylayer configuration. Restart OpenCode after configuration changes.

Plugin not loading

Ensure the plugin is listed in opencode.json:

{
  "plugin": ["@scitrera/memorylayer-opencode-plugin"]
}

License

Apache-2.0