Memlayer
MemLayer Plugins
A self-learning memory system for Claude Code, the Gemini CLI, and Codex CLI that enables persistent learning across task executions. Must be used with MemLayer.
Overview
MemLayer provides your AI agents with episodic memory capabilities, allowing them to:
- Log task executions as episodes with outcomes, errors, and context
- Extract patterns from past experiences, especially failures
- Promote proven strategies into reusable skills
- Retrieve relevant context before starting new tasks
- Learn from mistakes to avoid repeating them
Installation
One-Command Installers (curl)
Use these from the target project directory.
Gemini CLI
curl -fsSL https://raw.githubusercontent.com/shafty023/MemLayer-Plugin/main/install-gemini.sh | bash
This installs the Gemini plugin and configures memlayer MCP in .gemini/settings.json.
Then run /mcp auth memlayer in Gemini to complete MCP login.
By default, installer checkout ref is main (override with MEMLAYER_REPO_REF).
Claude Code
curl -fsSL https://raw.githubusercontent.com/shafty023/MemLayer-Plugin/main/install-claude.sh | bash
This adds the plugin marketplace, installs memory@ProcIQ, and configures the memlayer MCP server in Claude.
Codex CLI
curl -fsSL https://raw.githubusercontent.com/shafty023/MemLayer-Plugin/main/install-codex.sh | bash
This installs the memory-usage skill into ${CODEX_HOME:-~/.codex}/skills, updates the current repo's AGENTS.md, configures MCP, and prints the codex mcp login memlayer step for you to run explicitly.
By default, installer checkout ref is main (override with MEMLAYER_REPO_REF).
Claude Code
-
Add the marketplace to Claude Code:
/plugin marketplace add shafty023/MemLayer-Plugin -
Install the memory plugin:
/plugin install memory@ProcIQ -
Configure the prociq MCP server with your API key (see prociq.ai for setup)
For more details on plugin installation, see the official documentation.
Gemini CLI
See the Gemini Plugin Documentation for installation and setup instructions.
Codex CLI
See the Codex Plugin Documentation for installation and setup instructions.
Project Structure
MemLayer-Plugin/
├── .claude-plugin/ # Claude marketplace registration
├── codex/ # Codex CLI installer and policy template
│ ├── setup.sh
│ └── templates/
├── gemini/ # Gemini CLI installer and manifest
│ ├── manifest.json
│ └── setup.sh
└── plugins/
└── memory/ # Claude Code plugin and shared skill source
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── commands/ # CLI commands
│ ├── audit.md # /memory:audit - inspect memory state
│ ├── teach.md # /memory:teach - inject knowledge manually
│ └── forget.md # /memory:forget - remove episodes
├── hooks/ # Integration hooks
│ ├── hooks.json
│ └── scripts/
│ ├── session-start.sh
│ └── user-prompt.sh
└── skills/
└── memory-usage/
└── SKILL.md # Canonical memory system usage guide
Commands
/memory:audit [episodes|patterns|skills]
Inspect the current state of the memory system. Shows statistics, recent episodes, high-confidence patterns, and skill inventory.
/memory:teach <lesson>
Manually inject knowledge into the memory system without task execution.
/memory:teach When using Detox with animations, always add explicit waitFor timeouts of at least 5000ms
/memory:forget <episode-id|query>
Remove specific episodes from memory. Can search by query or delete by ID.
Core Concepts
Episodes
Records of task execution containing:
- Task goal and approach taken
- Outcome (success/partial/failure)
- Error details if applicable
- Tools used and file patterns involved
- Importance score (0.0–1.0)
Patterns
Derived learnings extracted from multiple episodes:
- Root cause analysis
- Recommended strategy
- Trigger conditions (errors, keywords, tools)
Skills
Mature, high-confidence patterns promoted to reusable knowledge that gets surfaced when relevant tasks arise.
Notes
Persistent freeform knowledge entries that never decay (unlike episodes):
- Recording important discoveries that shouldn't fade
- Documenting project-specific knowledge
- Manual teaching via
/memory:teachcommand - Reference material that should always be findable
Consolidation
Automatic processing that:
- Clusters similar episodes
- Extracts patterns from failures
- Decays old/low-value episodes
- Promotes patterns to skills
Memory Tools (MCP)
Episode Tools
| Tool | Purpose |
|---|---|
prociq_log_episode | Record task execution (async, non-blocking) |
prociq_retrieve_context | Get relevant past experiences before a task |
prociq_search_episodes | Search with filters (outcome, error_type, project) |
prociq_get_episode | Retrieve full episode by ID |
prociq_search_episodes_full | Semantic search returning full episodes |
prociq_forget_episodes | Delete episodes permanently |
prociq_archive_episode | Soft-delete episodes (reversible) |
Note Tools
| Tool | Purpose |
|---|---|
prociq_log_note | Store persistent freeform knowledge |
prociq_update_note | Modify existing note |
prociq_get_note | Retrieve note by ID |
prociq_search_notes | Search notes by content or tags |
prociq_delete_note | Remove note from storage |
Pattern & Skill Tools
| Tool | Purpose |
|---|---|
prociq_search_patterns | Search patterns with filters |
prociq_list_skills | List all available skills |
prociq_get_skill_content | Retrieve skill markdown by ID |
System Tools
| Tool | Purpose |
|---|---|
prociq_get_memory_stats | View memory health and statistics |
prociq_trigger_consolidation | Manually run memory maintenance |
Best Practices
When to Log
Do log:
- Failures (always, before retrying)
- Non-obvious solutions requiring investigation
- First-time task types
- Recurring problem categories (config, debugging, integration)
Don't log:
- Trivial fixes (typos, missing imports)
- Routine CRUD operations
- Pure research/exploration tasks
Importance Scoring
| Scenario | Score |
|---|---|
| Normal success | 0.2–0.3 |
| First-time task type | 0.5–0.6 |
| Learned something new | 0.7–0.8 |
| Critical discovery/failure | 0.9–1.0 |
Critical Rule: Log Failures First
Always log a failure before retrying. This captures the exact error context that would otherwise be lost after a successful retry.
How Hooks Work
- SessionStart — Reminds Claude about available memory tools
- UserPromptSubmit — Injects memory workflow into TodoWrite (check memory first, log outcome last)
- Stop — Reminds Claude to log failures and suggests reflection
License
MIT License — see LICENSE for details.
Author
Daniel Ochoa (@shafty023)
Links
- prociq.ai — Memory system backend
- Claude Code Documentation
- Gemini CLI Documentation
- Codex CLI Documentation
Server Config
{
"mcpServers": {
"prociq_mcp": {
"type": "http",
"url": "https://prociq.ai/mcp"
}
}
}