Content
# Human Memory — AI Agent Five-Layer Human-Like Memory Framework
Provide cross-session scenario memory, semantic knowledge, program skills, and code structure perception capabilities for AI Agents.
Built on top of [OpenCode](https://opencode.ai), driven by the open-mem plugin and three MCP servers.
## Architecture
```
┌──────────────────────────────────────────────────────┐
│ L4 Meta-Memory mcp-memory-engine* (Rust) │
├──────────────────────────────────────────────────────┤
│ L3a Semantic Knowledge Graph server-memory │
│ L3b Program Skills core-memory-mcp │
│ L3a+ Code Structure codebase-memory-mcp │
├──────────────────────────────────────────────────────┤
│ L2 Scenario Memory open-mem (plugin) │
├──────────────────────────────────────────────────────┤
│ L1 Working Memory LLM Context Window │
├──────────────────────────────────────────────────────┤
│ L0 Sensory Capture open-mem hooks │
└──────────────────────────────────────────────────────┘
```
| Layer | Function | Component | Usage |
|----|------|------|---------|
| **L0+L2** | Capture Historical Sessions + Recall | open-mem plugin | Automatic context injection, `mem-find`, `mem-create` |
| **L3a** | Knowledge Graph (Facts and Concepts) | memory-kg (MCP) | `search_nodes`, `create_entities`, `add_observations` |
| **L3b** | Reusable Skill Extraction | memory-skills (MCP) | `create_skill`, `list_skills`, `get_skill` |
| **L3a+** | Code Structure Intelligence | memory-code (MCP) | `search_graph`, `get_callers`, `get_callees` |
## Quick Start
**Environment Requirements:** OpenCode v1.17+, Node.js 20+ / Bun 1+
```bash
# 1. Add open-mem to global OpenCode configuration
# Edit ~/.config/opencode/opencode.jsonc:
# "plugin": ["oh-my-openagent@latest", "open-mem"]
# 2. Install open-mem
npm install open-mem
npx open-mem --quick
# 3. Add MCP server configuration to project's opencode.json
# (See configuration template below)
# 4. Restart OpenCode
```
### Project opencode.json Configuration
```json
{
"plugin": ["open-mem"],
"mcpServers": {
"memory-kg": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"],
"description": "Semantic Knowledge Graph"
},
"memory-skills": {
"type": "stdio",
"command": "core-memory",
"description": "Program Skill Extraction"
},
"memory-code": {
"type": "stdio",
"command": "codebase-memory-mcp",
"description": "Code Structure Intelligence"
}
},
"contextPaths": ["AGENTS.md", "MEMORY_ARCHITECTURE.md"]
}
```
### Install Optional MCP Servers
```bash
# memory-code — Code Structure (Recommended)
npx codebase-memory-mcp install opencode
# memory-skills — Program Skills (Requires compilation)
git clone https://github.com/danielmriley/core-memory-mcp
cd core-memory-mcp && npm install && npm run build && npm link
```
## Usage
Load skill in OpenCode:
```
skill(name="human-memory")
```
### Session Startup Protocol
```python
1. Read open-mem auto-injected context
2. memory-kg → search_nodes("") # Load project knowledge
3. memory-code → search_graph("") # Load code structure
```
### Working
```python
# Save learned knowledge:
memory-kg → create_entities() + add_observations()
memory-kg → create_relations() # Associate related entities
# Extract reusable patterns:
memory-skills → create_skill(confidence=0.7)
# Explore unfamiliar code:
memory-code → search_graph("module_name")
```
## Tool Reference
| Target | Invocation | MCP Server |
|------|---------|------------|
| Save Facts | `create_entities` + `add_observations` | memory-kg |
| Associate Entities | `create_relations` | memory-kg |
| Search Knowledge | `search_nodes(query)` | memory-kg |
| Browse Historical Sessions | `mem-find(query)` | open-mem |
| Create Skill | `create_skill()` | memory-skills |
| Find Skills | `list_skills(keyword)` | memory-skills |
| Explore Code | `search_graph(symbol)` | memory-code |
| Find Callers | `get_callers(function)` | memory-code |
## Project Structure
```
human-memory/
├── SKILL.md # Loadable skill definition
├── references/
│ └── MEMORY_ARCHITECTURE.md # Complete architecture design document
├── package.json # npm package definition
├── setup.sh # One-click installation script
├── LICENSE # MIT
└── README.md # This file
```
## License
MIT
