name	cognitive-memory
description	Intelligent multi-store memory system for OpenClaw agents with episodic logs, semantic graph memory, procedural memory, decay-aware retention, reflection workflows, and audit trails.

Cognitive Memory System

A memory architecture for OpenClaw agents that goes beyond a single flat MEMORY.md file.

It organizes memory into multiple stores:

• Core memory — always-loaded MEMORY.md
• Episodic memory — append-only daily logs
• Semantic memory — graph-style entities and relationships
• Procedural memory — learned workflows and patterns
• Vault memory — user-pinned facts that should not decay

It also includes:

• Decay tracking for prioritizing recall
• Reflection workflows for consolidation
• Git + audit log for mutation traceability
• Multi-agent staging via pending memory proposals

---

What this repo contains

• scripts/init_memory.sh — initialize the directory structure and starter files
• assets/templates/ — templates for memory files and agent instruction blocks
• references/ — design notes and deeper documentation
• SKILL.md — skill-facing usage instructions
• UPGRADE*.md / upgrade scripts — migration notes for older installs

---

Quick start

1. Clone or copy this repo

git clone https://github.com/yankel121160-coder/openclaw-cognitive-memory.git
cd openclaw-cognitive-memory

2. Initialize a workspace

bash scripts/init_memory.sh /path/to/openclaw-workspace

Example:

bash scripts/init_memory.sh ~/.openclaw/workspace

This creates the memory directory tree and copies starter templates without overwriting existing core files like MEMORY.md, IDENTITY.md, or SOUL.md.

3. Configure memory search in OpenClaw

Enable memory retrieval in your OpenClaw gateway/agent configuration using the current OpenClaw config path and schema for your install.

At a minimum, you want memory search enabled for:

• workspace memory files
• optionally session transcript chunks

If you are unsure about the exact config keys for your version, check the OpenClaw config schema/docs first rather than copying old config examples.

4. Add the memory instruction block to your agent rules

Append or adapt:

assets/templates/agents-memory-block.md

into your agent instructions (for example AGENTS.md or your agent’s system instructions).

5. Customize the identity layer

Review and edit:

• MEMORY.md
• IDENTITY.md
• SOUL.md

These three files define the always-loaded core memory and the agent’s stable self-model.

---

Resulting file structure

After initialization, the workspace looks roughly like this:

workspace/
├── MEMORY.md
├── IDENTITY.md
├── SOUL.md
├── memory/
│   ├── episodes/
│   ├── graph/
│   │   ├── index.md
│   │   ├── entities/
│   │   └── relations.md
│   ├── procedures/
│   ├── vault/
│   └── meta/
│       ├── decay-scores.json
│       ├── reflection-log.md
│       ├── reward-log.md
│       ├── reflections/
│       │   └── dialogues/
│       ├── rewards/
│       ├── pending-memories.md
│       ├── pending-reflection.md
│       ├── evolution.md
│       └── audit.log
└── .git/

---

Minimal usage example

Remembering a user preference

User says:

Remember that I prefer TypeScript over JavaScript.

Expected behavior:

• append an episode/log entry
• update semantic or core memory if appropriate
• update decay tracking / audit trail

Recalling a preference

User says:

What do you remember about my language preferences?

Expected behavior:

• check MEMORY.md first
• if needed, search semantic memory / episodic memory
• answer from the retrieved memory rather than hallucinating

Learning a procedure

User says:

Remember this workflow: run tests before every deploy.

Expected behavior:

• classify as procedural memory
• create or update a procedure file
• optionally promote to core memory if it is always relevant

---

Architecture summary

Core memory

• Small, always loaded
• Best for identity, active priorities, critical facts

Episodic memory

• Chronological, append-only
• Best for decisions, events, corrections, notable interactions

Semantic memory

• Entity/relationship oriented
• Best for people, projects, concepts, preferences, long-lived facts

Procedural memory

• Best for repeatable workflows and heuristics

Vault memory

• User-pinned memory that should not be automatically decayed or forgotten

---

Reflection and decay

This system supports two important higher-order behaviors:

Decay

Older memories can be deprioritized rather than instantly deleted. That keeps retrieval useful without pretending every old fact matters equally forever.

Reflection

A scheduled or manual reflection pass can:

• consolidate episodic logs into semantic memory
• rewrite core memory
• propose archival of stale entries
• record long-term evolution notes

See:

• references/reflection-process.md
• references/architecture.md

---

Multi-agent pattern

Sub-agents should usually read shared memory directly but write via proposals.

Recommended pattern:

• sub-agent writes proposal → memory/meta/pending-memories.md
• main/orchestrator agent reviews
• approved memories get committed into the real stores

This keeps shared memory coherent and auditable.

---

Current caveats

This repo is a memory architecture and workflow scaffold, not a full standalone memory database service.

You still need to integrate it with:

• your agent instructions
• your retrieval flow
• your OpenClaw config
• any automation for reflection / consolidation

---

Recommended next improvements

If you want to productionize it further, add:

• a concrete OpenClaw config example for current versions
• a small end-to-end demo
• a validator that checks required files after initialization
• a graph rebuild script
• tests for init / upgrade scripts

---

References

• references/architecture.md
• references/reflection-process.md
• references/routing-prompt.md

---

License / reuse

If you reuse this in another agent stack, keep the audit and approval model intact. That part matters as much as the memory structure itself.