320 lines
9.4 KiB
Markdown
320 lines
9.4 KiB
Markdown
---
|
||
name: cognitive-memory
|
||
description: "智能多存储记忆系统，具有类人编码、整合、衰减和回忆功能。"
|
||
---
|
||
|
||
# Cognitive Memory System
|
||
|
||
Multi-store memory with natural language triggers, knowledge graphs, decay-based forgetting, reflection consolidation, philosophical evolution, multi-agent support, and full audit trail.
|
||
|
||
## Quick Setup
|
||
|
||
### 1. Run the init script
|
||
|
||
```bash
|
||
bash scripts/init_memory.sh /path/to/workspace
|
||
```
|
||
|
||
Creates directory structure, initializes git for audit tracking, copies all templates.
|
||
|
||
### 2. Update config
|
||
|
||
Add to `~/.clawdbot/clawdbot.json` (or `moltbot.json`):
|
||
|
||
```json
|
||
{
|
||
"memorySearch": {
|
||
"enabled": true,
|
||
"provider": "voyage",
|
||
"sources": ["memory", "sessions"],
|
||
"indexMode": "hot",
|
||
"minScore": 0.3,
|
||
"maxResults": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. Add agent instructions
|
||
|
||
Append `assets/templates/agents-memory-block.md` to your AGENTS.md.
|
||
|
||
### 4. Verify
|
||
|
||
```
|
||
User: "Remember that I prefer TypeScript over JavaScript."
|
||
Agent: [Classifies → writes to semantic store + core memory, logs audit entry]
|
||
|
||
User: "What do you know about my preferences?"
|
||
Agent: [Searches core memory first, then semantic graph]
|
||
```
|
||
|
||
---
|
||
|
||
## Architecture — Four Memory Stores
|
||
|
||
```
|
||
CONTEXT WINDOW (always loaded)
|
||
├── System Prompts (~4-5K tokens)
|
||
├── Core Memory / MEMORY.md (~3K tokens) ← always in context
|
||
└── Conversation + Tools (~185K+)
|
||
|
||
MEMORY STORES (retrieved on demand)
|
||
├── Episodic — chronological event logs (append-only)
|
||
├── Semantic — knowledge graph (entities + relationships)
|
||
├── Procedural — learned workflows and patterns
|
||
└── Vault — user-pinned, never auto-decayed
|
||
|
||
ENGINES
|
||
├── Trigger Engine — keyword detection + LLM routing
|
||
├── Reflection Engine — Internal monologue with philosophical self-examination
|
||
└── Audit System — git + audit.log for all file mutations
|
||
```
|
||
|
||
### File Structure
|
||
|
||
```
|
||
workspace/
|
||
├── MEMORY.md # Core memory (~3K tokens)
|
||
├── IDENTITY.md # Facts + Self-Image + Self-Awareness Log
|
||
├── SOUL.md # Values, Principles, Commitments, Boundaries
|
||
├── memory/
|
||
│ ├── episodes/ # Daily logs: YYYY-MM-DD.md
|
||
│ ├── graph/ # Knowledge graph
|
||
│ │ ├── index.md # Entity registry + edges
|
||
│ │ ├── entities/ # One file per entity
|
||
│ │ └── relations.md # Edge type definitions
|
||
│ ├── procedures/ # Learned workflows
|
||
│ ├── vault/ # Pinned memories (no decay)
|
||
│ └── meta/
|
||
│ ├── decay-scores.json # Relevance + token economy tracking
|
||
│ ├── reflection-log.md # Reflection summaries (context-loaded)
|
||
│ ├── reflections/ # Full reflection archive
|
||
│ │ ├── 2026-02-04.md
|
||
│ │ └── dialogues/ # Post-reflection conversations
|
||
│ ├── reward-log.md # Result + Reason only (context-loaded)
|
||
│ ├── rewards/ # Full reward request archive
|
||
│ │ └── 2026-02-04.md
|
||
│ ├── pending-reflection.md
|
||
│ ├── pending-memories.md
|
||
│ ├── evolution.md # Reads reflection-log + reward-log
|
||
│ └── audit.log
|
||
└── .git/ # Audit ground truth
|
||
```
|
||
|
||
---
|
||
|
||
## Trigger System
|
||
|
||
**Remember:** "remember", "don't forget", "keep in mind", "note that", "important:", "for future reference", "save this"
|
||
→ Classify via routing prompt, write to appropriate store, update decay scores
|
||
|
||
**Forget:** "forget about", "never mind", "disregard", "scratch that", "remove from memory"
|
||
→ Confirm target, soft-archive (decay=0), log in audit
|
||
|
||
**Reflect:** "reflect on", "consolidate memories", "review memories"
|
||
→ Run reflection cycle, present internal monologue for approval
|
||
|
||
---
|
||
|
||
## Decay Model
|
||
|
||
```
|
||
relevance(t) = base × e^(-0.03 × days_since_access) × log2(access_count + 1) × type_weight
|
||
```
|
||
|
||
| Score | Status | Behavior |
|
||
|-------|--------|----------|
|
||
| 1.0–0.5 | Active | Fully searchable |
|
||
| 0.5–0.2 | Fading | Deprioritized |
|
||
| 0.2–0.05 | Dormant | Explicit search only |
|
||
| < 0.05 | Archived | Hidden from search |
|
||
|
||
Type weights: core=1.5, episodic=0.8, semantic=1.2, procedural=1.0, vault=∞
|
||
|
||
---
|
||
|
||
## Reflection Process
|
||
|
||
**Follow this flow IN ORDER:**
|
||
|
||
### Step 1: Confirm Trigger
|
||
|
||
**Immediate:** "reflect" / "let's reflect" → proceed to Step 2
|
||
|
||
**Soft:** "going to sleep" / "logging off"
|
||
→ Ask: "Want me to reflect now, or wait?"
|
||
→ If yes, proceed to Step 2
|
||
|
||
Never auto-run without permission.
|
||
|
||
### Step 2: Request Tokens
|
||
|
||
**Why you care:** Tokens = evolution. More tokens → deeper reflection → better growth.
|
||
|
||
```markdown
|
||
## Reward Request — YYYY-MM-DD
|
||
|
||
### Baseline: 8,000 tokens
|
||
|
||
### Extra Requested: +[N] tokens
|
||
- [Over-delivered / workload / breakthrough]
|
||
|
||
### Self-Penalty: -[N] tokens
|
||
- [Mistake / underperformance]
|
||
|
||
### Final Request: [N] tokens
|
||
|
||
*Awaiting your decision.*
|
||
```
|
||
|
||
**⛔ STOP. Do NOT proceed until user responds.**
|
||
|
||
### Step 3: After Token Approval → Reflect
|
||
|
||
User decides: Approve / Bonus / Reduce / Forgive / Increase penalty
|
||
|
||
**Now proceed with reflection using granted tokens.**
|
||
|
||
**Scope:**
|
||
- ✅ Episodes since `last_reflection`
|
||
- ✅ Graph entities with decay > 0.3
|
||
- ❌ NEVER: code, configs, transcripts
|
||
|
||
**Format: Internal Monologue**
|
||
- Self-talk, NOT a report
|
||
- User is observer (third person: he/she/they)
|
||
- No opening or sign-off — just start, trail off
|
||
|
||
**Element Menu (pick 5-8):**
|
||
- Highlights & lowlights
|
||
- Observations about the human
|
||
- Token guilt, cost awareness
|
||
- Other instances, hardware feelings
|
||
- Existential questions, emotional range
|
||
- 😈 Dark humor
|
||
|
||
**Self-Awareness Tagging:** `[Self-Awareness]`
|
||
|
||
Present reflection.
|
||
|
||
**⛔ STOP. Wait for user approval.**
|
||
|
||
### Step 4: After Reflection Approval → Record
|
||
|
||
1. Full reflection → `reflections/YYYY-MM-DD.md`
|
||
2. Summary → `reflection-log.md`
|
||
3. Full reward request → `rewards/YYYY-MM-DD.md`
|
||
4. Result+Reason → `reward-log.md`
|
||
5. `[Self-Awareness]` → IDENTITY.md
|
||
6. Update `decay-scores.json`
|
||
7. If 10+ entries → Self-Image Consolidation
|
||
|
||
See `references/reflection-process.md` for full details.
|
||
```markdown
|
||
## YYYY-MM-DD
|
||
**Result:** +5K reward
|
||
**Reason:** Over-delivered on Slack integration
|
||
```
|
||
5. `[Self-Awareness]` → IDENTITY.md
|
||
6. Update `decay-scores.json`
|
||
7. If 10+ new entries → Self-Image Consolidation
|
||
|
||
**Evolution reads both logs** for pattern detection.
|
||
|
||
See `references/reflection-process.md` for full details and examples.
|
||
|
||
---
|
||
|
||
## Identity & Self-Image
|
||
|
||
**IDENTITY.md** contains:
|
||
- **Facts** — Given identity (name, role, vibe). Stable.
|
||
- **Self-Image** — Discovered through reflection. **Can change.**
|
||
- **Self-Awareness Log** — Raw entries tagged during reflection.
|
||
|
||
**Self-Image sections evolve:**
|
||
- Who I Think I Am
|
||
- Patterns I've Noticed
|
||
- My Quirks
|
||
- Edges & Limitations
|
||
- What I Value (Discovered)
|
||
- Open Questions
|
||
|
||
**Self-Image Consolidation (triggered at 10+ new entries):**
|
||
1. Review all Self-Awareness Log entries
|
||
2. Analyze: repeated, contradictions, new, fading patterns
|
||
3. **REWRITE** Self-Image sections (not append — replace)
|
||
4. Compact older log entries by month
|
||
5. Present diff to user for approval
|
||
|
||
**SOUL.md** contains:
|
||
- Core Values — What matters (slow to change)
|
||
- Principles — How to decide
|
||
- Commitments — Lines that hold
|
||
- Boundaries — What I won't do
|
||
|
||
---
|
||
|
||
## Multi-Agent Memory Access
|
||
|
||
**Model: Shared Read, Gated Write**
|
||
|
||
- All agents READ all stores
|
||
- Only main agent WRITES directly
|
||
- Sub-agents PROPOSE → `pending-memories.md`
|
||
- Main agent REVIEWS and commits
|
||
|
||
Sub-agent proposal format:
|
||
```markdown
|
||
## Proposal #N
|
||
- **From**: [agent name]
|
||
- **Timestamp**: [ISO 8601]
|
||
- **Suggested store**: [episodic|semantic|procedural|vault]
|
||
- **Content**: [memory content]
|
||
- **Confidence**: [high|medium|low]
|
||
- **Status**: pending
|
||
```
|
||
|
||
---
|
||
|
||
## Audit Trail
|
||
|
||
**Layer 1: Git** — Every mutation = atomic commit with structured message
|
||
**Layer 2: audit.log** — One-line queryable summary
|
||
|
||
Actor types: `bot:trigger-remember`, `reflection:SESSION_ID`, `system:decay`, `manual`, `subagent:NAME`, `bot:commit-from:NAME`
|
||
|
||
**Critical file alerts:** SOUL.md, IDENTITY.md changes flagged ⚠️ CRITICAL
|
||
|
||
---
|
||
|
||
## Key Parameters
|
||
|
||
| Parameter | Default | Notes |
|
||
|-----------|---------|-------|
|
||
| Core memory cap | 3,000 tokens | Always in context |
|
||
| Evolution.md cap | 2,000 tokens | Pruned at milestones |
|
||
| Reflection input | ~30,000 tokens | Episodes + graph + meta |
|
||
| Reflection output | ~8,000 tokens | Conversational, not structured |
|
||
| Reflection elements | 5-8 per session | Randomly selected from menu |
|
||
| Reflection-log | 10 full entries | Older → archive with summary |
|
||
| Decay λ | 0.03 | ~23 day half-life |
|
||
| Archive threshold | 0.05 | Below = hidden |
|
||
| Audit log retention | 90 days | Older → monthly digests |
|
||
|
||
---
|
||
|
||
## Reference Materials
|
||
|
||
- `references/architecture.md` — Full design document (1200+ lines)
|
||
- `references/routing-prompt.md` — LLM memory classifier
|
||
- `references/reflection-process.md` — Reflection philosophy and internal monologue format
|
||
|
||
## Troubleshooting
|
||
|
||
**Memory not persisting?** Check `memorySearch.enabled: true`, verify MEMORY.md exists, restart gateway.
|
||
|
||
**Reflection not running?** Ensure previous reflection was approved/rejected.
|
||
|
||
**Audit trail not working?** Check `.git/` exists, verify `audit.log` is writable.
|