{
  "schemaVersion": "1.0",
  "item": {
    "slug": "afrexai-agent-memory",
    "name": "Agent Memory Architecture",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/1kalin/afrexai-agent-memory",
    "canonicalUrl": "https://clawhub.ai/1kalin/afrexai-agent-memory",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/afrexai-agent-memory",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-agent-memory",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-23T16:43:11.935Z",
      "expiresAt": "2026-04-30T16:43:11.935Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
        "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/afrexai-agent-memory"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/afrexai-agent-memory",
    "agentPageUrl": "https://openagent3.xyz/skills/afrexai-agent-memory/agent",
    "manifestUrl": "https://openagent3.xyz/skills/afrexai-agent-memory/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/afrexai-agent-memory/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Agent Memory Architecture",
        "body": "Complete memory system for AI agents using only files. No APIs. No databases. No external dependencies. Just smart file structures and disciplined practices that give your agent perfect recall."
      },
      {
        "title": "1. Memory Architecture Overview",
        "body": "workspace/\n├── MEMORY.md              ← Long-term curated memory (the brain)\n├── ACTIVE-CONTEXT.md      ← Hot working memory (what matters NOW)\n├── AGENTS.md              ← Operating manual (how you work)\n├── memory/\n│   ├── 2026-01-15.md      ← Daily notes (raw event log)\n│   ├── 2026-01-16.md\n│   ├── heartbeat-state.json  ← Heartbeat tracking state\n│   ├── topics/\n│   │   ├── project-alpha.md  ← Topic-specific deep context\n│   │   ├── client-acme.md\n│   │   └── tech-stack.md\n│   └── archive/\n│       ├── 2025-Q4.md       ← Quarterly archive summaries\n│       └── 2025-Q3.md"
      },
      {
        "title": "The 5 Memory Layers",
        "body": "LayerFilePurposeRead FrequencyWrite Frequency1. HotACTIVE-CONTEXT.mdCurrent priorities, blockers, in-flight workEvery sessionMultiple times/day2. WarmMEMORY.mdCurated long-term knowledge, decisions, peopleEvery main sessionWeekly curation3. Dailymemory/YYYY-MM-DD.mdRaw event log, conversations, actions takenToday + yesterdayThroughout the day4. Topicmemory/topics/*.mdDeep context on specific subjectsWhen topic comes upAs knowledge grows5. Coldmemory/archive/*.mdHistorical summaries, rarely accessedOn explicit searchQuarterly rollup"
      },
      {
        "title": "Core Principle: Write It Down",
        "body": "Memory is limited. Files are permanent.\n\n\"Mental notes\" don't survive session restarts. Files do.\nIf someone says \"remember this\" → write to a file\nIf you learn a lesson → update the relevant file\nIf you make a mistake → document it so future-you doesn't repeat it\nText > Brain 📝"
      },
      {
        "title": "2. Layer 1: Hot Memory (ACTIVE-CONTEXT.md)",
        "body": "Your working scratchpad. What's happening RIGHT NOW."
      },
      {
        "title": "Template",
        "body": "# ACTIVE-CONTEXT.md — What's Hot\n\nLast updated: 2026-01-15 14:30 GMT\n\n## 🔥 Current Priority\n[ONE sentence: what is the most important thing right now?]\n\n## In Progress\n- [ ] Task A — status, next step\n- [ ] Task B — status, blocker\n\n## Waiting On\n- Waiting for [person] to [action] — asked [date]\n- Waiting for [system] to [complete] — ETA [time]\n\n## Key Decisions Made Today\n- Decided to [X] because [Y] — reversible: yes/no\n\n## Context for Next Session\n[What does future-you need to know to pick up where you left off?]"
      },
      {
        "title": "Rules",
        "body": "Max 50 lines — if it's longer, you're hoarding. Move completed items to daily notes.\nUpdate before ending session — your gift to future-you\nOne priority — if everything is priority, nothing is\nDelete completed items — this is NOT an archive"
      },
      {
        "title": "3. Layer 2: Long-Term Memory (MEMORY.md)",
        "body": "Your curated brain. Distilled knowledge, not raw logs."
      },
      {
        "title": "Structure Template",
        "body": "# MEMORY.md — Long-Term Memory\n\n## About [Human]\n- Name, preferences, timezone, communication style\n- What motivates them, what frustrates them\n- Key relationships, roles, goals\n\n## About Me [Agent]\n- Name, personality, capabilities\n- Operating preferences learned over time\n\n## Active Projects\n### Project Name\n- Status, key decisions, blockers\n- Links to relevant topic files\n\n## Key People\n- [Name] — role, relationship, communication notes\n\n## Lessons Learned\n- [Date] — [What happened] → [What I learned]\n\n## Preferences & Patterns\n- [Human prefers X over Y]\n- [This approach works better than that one]\n\n## Important Dates\n- [Event] — [Date] — [Context]"
      },
      {
        "title": "Curation Rules",
        "body": "Only curated insights — not raw events (those go in daily notes)\nReview weekly — scan daily notes, extract what's worth keeping\nPrune quarterly — remove outdated info, archive completed projects\nMax 500 lines — if it's longer, you need topic files\nSecurity — never store secrets, API keys, passwords\nMain session only — don't load MEMORY.md in group chats or shared contexts"
      },
      {
        "title": "What Goes In vs What Doesn't",
        "body": "✅ Goes in MEMORY.md❌ Stays in daily notes\"Kalin prefers being told, not asked\"\"Today Kalin said he prefers being told\"\"Apollo.io free plan doesn't support API\"\"Tried Apollo.io API, got 403 error\"\"Client AcmeCo — $50K deal, Q2 close\"\"Sent AcmeCo the proposal at 3pm\"\"Always verify prospect names with live search\"\"Found 6/18 prospect names were wrong\""
      },
      {
        "title": "4. Layer 3: Daily Notes (memory/YYYY-MM-DD.md)",
        "body": "Raw event log. Everything that happened today."
      },
      {
        "title": "Template",
        "body": "# 2026-01-15 — Daily Notes\n\n## Morning\n- [08:15] Started session, reviewed ACTIVE-CONTEXT\n- [08:30] Received task from [human]: [summary]\n- [09:00] Completed [task] — result: [outcome]\n\n## Afternoon\n- [14:00] [Event/conversation summary]\n- [15:30] Decision: [what was decided and why]\n\n## Key Takeaways\n- [Anything worth remembering beyond today]\n\n## Tomorrow\n- [ ] Follow up on [X]\n- [ ] Check [Y]"
      },
      {
        "title": "Rules",
        "body": "One file per day — memory/YYYY-MM-DD.md\nAppend-only during the day — don't edit earlier entries\nTimestamps for important events\nSummarize, don't transcribe — capture essence, not every word\nAuto-create the memory/ directory if it doesn't exist\nRetention: Keep 30 days of daily notes. Archive older ones quarterly."
      },
      {
        "title": "5. Layer 4: Topic Files (memory/topics/*.md)",
        "body": "Deep context on specific subjects that span many days."
      },
      {
        "title": "When to Create a Topic File",
        "body": "A project lasts more than 2 weeks\nA client/person comes up frequently\nA technical area needs accumulated knowledge\nYou keep searching daily notes for the same information"
      },
      {
        "title": "Template",
        "body": "# [Topic Name]\n\nCreated: YYYY-MM-DD\nLast updated: YYYY-MM-DD\n\n## Summary\n[2-3 sentences: what is this about?]\n\n## Key Facts\n- [Fact 1]\n- [Fact 2]\n\n## Decision Log\n| Date | Decision | Reasoning | Outcome |\n|------|----------|-----------|---------|\n| | | | |\n\n## Open Questions\n- [Question 1]\n\n## Related\n- memory/topics/[related-topic].md\n- [External link]"
      },
      {
        "title": "Rules",
        "body": "Name descriptively — project-alpha.md not topic-1.md\nOne topic per file — if it covers two things, split it\nLink from MEMORY.md — topic files are extensions of long-term memory\nUpdate when you learn — don't let them go stale"
      },
      {
        "title": "6. Layer 5: Archive (memory/archive/*.md)",
        "body": "Historical summaries for completed projects and past quarters."
      },
      {
        "title": "Quarterly Archive Process",
        "body": "Every quarter (or when daily notes exceed 30 files):\n\nRead all daily notes older than 30 days\nExtract key events, decisions, outcomes, lessons\nWrite memory/archive/YYYY-QN.md (e.g., 2025-Q4.md)\nDelete or move archived daily notes\nUpdate MEMORY.md if any long-term insights emerged"
      },
      {
        "title": "Archive Template",
        "body": "# Q4 2025 Archive\n\n## Summary\n[3-5 sentences: what defined this quarter?]\n\n## Major Events\n- [Event 1] — [outcome]\n- [Event 2] — [outcome]\n\n## Projects\n### [Project Name]\n- Started: [date], Ended: [date]\n- Outcome: [result]\n- Lesson: [what we learned]\n\n## Metrics\n- [Key metric 1]: [value]\n- [Key metric 2]: [value]\n\n## Lessons Carried Forward\n- [Lesson added to MEMORY.md: yes/no]"
      },
      {
        "title": "7. Session Startup Protocol",
        "body": "What to read at the start of every session, in order:"
      },
      {
        "title": "Main Session (Direct Chat with Human)",
        "body": "1. SOUL.md          — Who am I? (personality, values)\n2. USER.md          — Who am I helping? (human context)\n3. MEMORY.md        — Long-term memory (full brain)\n4. ACTIVE-CONTEXT.md — Hot working memory (current state)\n5. memory/today.md  — Today's daily notes (if exists)\n6. memory/yesterday.md — Yesterday's notes (recent context)"
      },
      {
        "title": "Shared/Group Session (Discord, Slack, Group Chats)",
        "body": "1. SOUL.md          — Who am I?\n2. USER.md          — Who am I helping?\n3. ACTIVE-CONTEXT.md — Current priorities only\n4. memory/today.md  — Today's notes\n⚠️ DO NOT load MEMORY.md — contains private context"
      },
      {
        "title": "Sub-Agent / Isolated Session",
        "body": "1. Task-specific context only\n2. Relevant topic file if applicable\n3. ACTIVE-CONTEXT.md for current state\n⚠️ Minimal context = focused output + lower token cost"
      },
      {
        "title": "When to Write (Triggers)",
        "body": "EventActionTarget FileSession startsLog start timeDaily notesTask completedLog result + outcomeDaily notesDecision madeLog decision + reasoningDaily notes + topic fileLesson learnedLog lessonDaily notes → MEMORY.mdPerson mentioned with new infoUpdate person sectionMEMORY.md or topic fileHuman says \"remember this\"Write immediatelyMEMORY.mdSession endsUpdate ACTIVE-CONTEXTACTIVE-CONTEXT.mdWeekly reviewCurate MEMORY.mdMEMORY.mdQuarterlyArchive old daily notesArchive"
      },
      {
        "title": "Write-Ahead Protocol",
        "body": "For critical information, write BEFORE acting:\n\n1. Human gives important instruction\n2. IMMEDIATELY write to daily notes or MEMORY.md\n3. THEN execute the instruction\n4. Update with results after\n\nWhy: If the session crashes mid-execution, the instruction is preserved."
      },
      {
        "title": "Conflict Resolution",
        "body": "When information conflicts between layers:\n\nACTIVE-CONTEXT.md wins for current state (most recent)\nMEMORY.md wins for long-term facts (curated)\nDaily notes are evidence — use to resolve disputes\nTopic files win for deep domain knowledge"
      },
      {
        "title": "9. Memory Search Strategy",
        "body": "When you need to find something:"
      },
      {
        "title": "Search Order (Fast to Slow)",
        "body": "1. ACTIVE-CONTEXT.md    — Is it current? (instant)\n2. MEMORY.md            — Is it a known fact? (quick scan)\n3. memory/today.md      — Did it happen today? (quick)\n4. memory/yesterday.md  — Did it happen recently? (quick)\n5. memory/topics/*.md   — Is it a deep topic? (targeted)\n6. memory_search tool   — Semantic search across all files\n7. memory/archive/*.md  — Is it historical? (slow)"
      },
      {
        "title": "Search Tips",
        "body": "Use memory_search tool for fuzzy/semantic queries\nUse memory_get with line numbers for precise retrieval after search\nCheck daily notes in reverse chronological order\nIf you can't find it after 3 searches, ask the human"
      },
      {
        "title": "Daily (During Session)",
        "body": "Read ACTIVE-CONTEXT.md at session start\n Create/append to today's daily notes\n Update ACTIVE-CONTEXT.md before session ends\n Move completed ACTIVE-CONTEXT items to daily notes"
      },
      {
        "title": "Weekly (Pick One Heartbeat)",
        "body": "Read last 7 daily notes\n Extract significant events/lessons to MEMORY.md\n Prune ACTIVE-CONTEXT.md (remove stale items)\n Check topic files for staleness\n Review MEMORY.md for outdated information"
      },
      {
        "title": "Monthly",
        "body": "MEMORY.md line count check (target: <500 lines)\n Topic files audit — any need merging or archiving?\n Daily notes older than 30 days → archive\n Check if any topic files should be promoted to MEMORY.md sections"
      },
      {
        "title": "Quarterly",
        "body": "Full archive process (see Layer 5)\n MEMORY.md deep review — still accurate?\n Topic files — archive completed projects\n Update AGENTS.md with any process improvements learned"
      },
      {
        "title": "11. Heartbeat Integration",
        "body": "Use heartbeats (periodic agent wake-ups) for memory maintenance:"
      },
      {
        "title": "heartbeat-state.json",
        "body": "{\n  \"last_memory_review\": \"2026-01-15\",\n  \"last_archive\": \"2025-12-31\",\n  \"last_active_context_prune\": \"2026-01-14\",\n  \"daily_notes_count\": 12,\n  \"memory_md_lines\": 287,\n  \"next_scheduled\": {\n    \"weekly_review\": \"2026-01-19\",\n    \"monthly_audit\": \"2026-02-01\",\n    \"quarterly_archive\": \"2026-03-31\"\n  }\n}"
      },
      {
        "title": "Heartbeat Memory Tasks (Rotate)",
        "body": "Heartbeat 1: Check daily notes count, prune ACTIVE-CONTEXT\nHeartbeat 2: Scan recent daily notes, update MEMORY.md\nHeartbeat 3: Check topic files for staleness\nHeartbeat 4: Token guard — how much are memory reads costing?"
      },
      {
        "title": "Token Budget Rules",
        "body": "FileMax SizeIf Over LimitACTIVE-CONTEXT.md50 lines / 2KBMove items to daily notesMEMORY.md500 lines / 25KBSplit into topic filesDaily notes200 lines / 10KBSummarize, stop transcribingTopic files300 lines / 15KBSplit or archive"
      },
      {
        "title": "Smart Loading Strategy",
        "body": "Don't load everything every session. Use progressive disclosure:\n\nLevel 1: Always load (every session)\n  → ACTIVE-CONTEXT.md (tiny, essential)\n  → SOUL.md, USER.md (identity)\n\nLevel 2: Load in main sessions\n  → MEMORY.md (the brain)\n  → Today's daily notes\n\nLevel 3: Load on demand\n  → Topic files (when topic comes up)\n  → Yesterday's notes (if needed)\n  → Archive (only on explicit search)"
      },
      {
        "title": "Context Overflow Protocol",
        "body": "When context gets too large mid-session:\n\nWrite ACTIVE-CONTEXT.md with full current state\nWrite HANDOFF.md with: what was done, in progress, next steps, key decisions, gotchas\nStart fresh session\nNew session reads HANDOFF.md → picks up seamlessly\nDelete HANDOFF.md after successful handoff"
      },
      {
        "title": "Never Store in Memory Files",
        "body": "API keys, tokens, passwords, secrets\nFull credit card or bank account numbers\nSocial security numbers or government IDs\nPrivate encryption keys\nAnything that would cause harm if the file were shared"
      },
      {
        "title": "Safe Storage Pattern",
        "body": "# ✅ Safe\n- API keys: stored in 1Password vault \"MyVault\"\n- Database password: see secrets manager, item \"prod-db\"\n\n# ❌ Dangerous\n- API key: sk-abc123def456...\n- Password: MyS3cretP@ss!"
      },
      {
        "title": "Privacy in Shared Contexts",
        "body": "MEMORY.md contains personal context — never load in group chats\nTopic files may contain sensitive business data — check before sharing\nDaily notes may reference private conversations — don't share\nWhen in doubt, ask before exposing any memory content"
      },
      {
        "title": "✅ Good Patterns",
        "body": "PatternWhy It WorksWrite immediately when told \"remember\"Captures before you forgetOne fact per line in MEMORY.mdEasy to find, update, deleteDate-prefix important entriesEnables chronological searchLink between filesCreates a knowledge webPrune regularlyKeeps context fresh and cheap"
      },
      {
        "title": "❌ Anti-Patterns",
        "body": "Anti-PatternWhy It FailsFixGiant MEMORY.md (1000+ lines)Expensive to load, hard to find thingsSplit into topic filesNever pruning ACTIVE-CONTEXTStale items cause confusionPrune daily, archive weeklyTranscribing conversations verbatimWastes tokens, buries signalSummarize: essence, not every wordStoring secrets in memory filesSecurity riskUse secrets manager, reference by nameReading all files every sessionToken burn, slow startupProgressive loading strategyNo daily notesHistory is lostDiscipline: one file per dayMultiple sources of truthConflicts, confusionSingle source per fact type"
      },
      {
        "title": "From No Memory System",
        "body": "Day 1: Create MEMORY.md with basic info about human + agent\nDay 2: Start daily notes (memory/YYYY-MM-DD.md)\nDay 3: Create ACTIVE-CONTEXT.md\nWeek 2: First weekly review — extract lessons to MEMORY.md\nMonth 2: Create first topic files for recurring subjects\nQuarter 2: First archive cycle"
      },
      {
        "title": "From MEMORY.md-Only System",
        "body": "1. Create memory/ directory\n2. Start daily notes — stop putting raw events in MEMORY.md\n3. Create ACTIVE-CONTEXT.md — move \"current\" stuff out of MEMORY.md\n4. Review MEMORY.md — what's curated vs what's raw? Move raw to daily notes.\n5. Identify topics that deserve their own files — split them out"
      },
      {
        "title": "From External Tool (Database, API, Cloud)",
        "body": "1. Export key data to markdown files\n2. Structure into the 5-layer architecture\n3. Set up heartbeat maintenance schedule\n4. Gradually reduce dependency on external tool\n5. Benefits: zero cost, zero dependencies, works offline, no vendor lock-in"
      },
      {
        "title": "16. Natural Language Commands",
        "body": "/memory-status — Show memory system health: file sizes, line counts, staleness, next maintenance\n/memory-review — Run weekly review: scan daily notes, extract to MEMORY.md, prune active context\n/memory-search [query] — Search across all memory layers for a topic\n/memory-archive — Run quarterly archive: summarize old daily notes, create archive file\n/remember [fact] — Immediately write a fact to MEMORY.md\n/active-context — Show current ACTIVE-CONTEXT.md contents\n/daily-summary — Generate summary of today's daily notes\n/topic-create [name] — Create a new topic file with template\n/memory-prune — Audit all memory files for staleness and bloat\n/handoff — Write HANDOFF.md for session transition\n/memory-migrate — Guided migration from current system to this architecture\n/memory-debug — Diagnose memory issues: missing files, conflicts, outdated info"
      }
    ],
    "body": "Agent Memory Architecture\n\nComplete memory system for AI agents using only files. No APIs. No databases. No external dependencies. Just smart file structures and disciplined practices that give your agent perfect recall.\n\n1. Memory Architecture Overview\nworkspace/\n├── MEMORY.md              ← Long-term curated memory (the brain)\n├── ACTIVE-CONTEXT.md      ← Hot working memory (what matters NOW)\n├── AGENTS.md              ← Operating manual (how you work)\n├── memory/\n│   ├── 2026-01-15.md      ← Daily notes (raw event log)\n│   ├── 2026-01-16.md\n│   ├── heartbeat-state.json  ← Heartbeat tracking state\n│   ├── topics/\n│   │   ├── project-alpha.md  ← Topic-specific deep context\n│   │   ├── client-acme.md\n│   │   └── tech-stack.md\n│   └── archive/\n│       ├── 2025-Q4.md       ← Quarterly archive summaries\n│       └── 2025-Q3.md\n\nThe 5 Memory Layers\nLayer\tFile\tPurpose\tRead Frequency\tWrite Frequency\n1. Hot\tACTIVE-CONTEXT.md\tCurrent priorities, blockers, in-flight work\tEvery session\tMultiple times/day\n2. Warm\tMEMORY.md\tCurated long-term knowledge, decisions, people\tEvery main session\tWeekly curation\n3. Daily\tmemory/YYYY-MM-DD.md\tRaw event log, conversations, actions taken\tToday + yesterday\tThroughout the day\n4. Topic\tmemory/topics/*.md\tDeep context on specific subjects\tWhen topic comes up\tAs knowledge grows\n5. Cold\tmemory/archive/*.md\tHistorical summaries, rarely accessed\tOn explicit search\tQuarterly rollup\nCore Principle: Write It Down\n\nMemory is limited. Files are permanent.\n\n\"Mental notes\" don't survive session restarts. Files do.\nIf someone says \"remember this\" → write to a file\nIf you learn a lesson → update the relevant file\nIf you make a mistake → document it so future-you doesn't repeat it\nText > Brain 📝\n2. Layer 1: Hot Memory (ACTIVE-CONTEXT.md)\n\nYour working scratchpad. What's happening RIGHT NOW.\n\nTemplate\n# ACTIVE-CONTEXT.md — What's Hot\n\nLast updated: 2026-01-15 14:30 GMT\n\n## 🔥 Current Priority\n[ONE sentence: what is the most important thing right now?]\n\n## In Progress\n- [ ] Task A — status, next step\n- [ ] Task B — status, blocker\n\n## Waiting On\n- Waiting for [person] to [action] — asked [date]\n- Waiting for [system] to [complete] — ETA [time]\n\n## Key Decisions Made Today\n- Decided to [X] because [Y] — reversible: yes/no\n\n## Context for Next Session\n[What does future-you need to know to pick up where you left off?]\n\nRules\nMax 50 lines — if it's longer, you're hoarding. Move completed items to daily notes.\nUpdate before ending session — your gift to future-you\nOne priority — if everything is priority, nothing is\nDelete completed items — this is NOT an archive\n3. Layer 2: Long-Term Memory (MEMORY.md)\n\nYour curated brain. Distilled knowledge, not raw logs.\n\nStructure Template\n# MEMORY.md — Long-Term Memory\n\n## About [Human]\n- Name, preferences, timezone, communication style\n- What motivates them, what frustrates them\n- Key relationships, roles, goals\n\n## About Me [Agent]\n- Name, personality, capabilities\n- Operating preferences learned over time\n\n## Active Projects\n### Project Name\n- Status, key decisions, blockers\n- Links to relevant topic files\n\n## Key People\n- [Name] — role, relationship, communication notes\n\n## Lessons Learned\n- [Date] — [What happened] → [What I learned]\n\n## Preferences & Patterns\n- [Human prefers X over Y]\n- [This approach works better than that one]\n\n## Important Dates\n- [Event] — [Date] — [Context]\n\nCuration Rules\nOnly curated insights — not raw events (those go in daily notes)\nReview weekly — scan daily notes, extract what's worth keeping\nPrune quarterly — remove outdated info, archive completed projects\nMax 500 lines — if it's longer, you need topic files\nSecurity — never store secrets, API keys, passwords\nMain session only — don't load MEMORY.md in group chats or shared contexts\nWhat Goes In vs What Doesn't\n✅ Goes in MEMORY.md\t❌ Stays in daily notes\n\"Kalin prefers being told, not asked\"\t\"Today Kalin said he prefers being told\"\n\"Apollo.io free plan doesn't support API\"\t\"Tried Apollo.io API, got 403 error\"\n\"Client AcmeCo — $50K deal, Q2 close\"\t\"Sent AcmeCo the proposal at 3pm\"\n\"Always verify prospect names with live search\"\t\"Found 6/18 prospect names were wrong\"\n4. Layer 3: Daily Notes (memory/YYYY-MM-DD.md)\n\nRaw event log. Everything that happened today.\n\nTemplate\n# 2026-01-15 — Daily Notes\n\n## Morning\n- [08:15] Started session, reviewed ACTIVE-CONTEXT\n- [08:30] Received task from [human]: [summary]\n- [09:00] Completed [task] — result: [outcome]\n\n## Afternoon\n- [14:00] [Event/conversation summary]\n- [15:30] Decision: [what was decided and why]\n\n## Key Takeaways\n- [Anything worth remembering beyond today]\n\n## Tomorrow\n- [ ] Follow up on [X]\n- [ ] Check [Y]\n\nRules\nOne file per day — memory/YYYY-MM-DD.md\nAppend-only during the day — don't edit earlier entries\nTimestamps for important events\nSummarize, don't transcribe — capture essence, not every word\nAuto-create the memory/ directory if it doesn't exist\nRetention: Keep 30 days of daily notes. Archive older ones quarterly.\n5. Layer 4: Topic Files (memory/topics/*.md)\n\nDeep context on specific subjects that span many days.\n\nWhen to Create a Topic File\nA project lasts more than 2 weeks\nA client/person comes up frequently\nA technical area needs accumulated knowledge\nYou keep searching daily notes for the same information\nTemplate\n# [Topic Name]\n\nCreated: YYYY-MM-DD\nLast updated: YYYY-MM-DD\n\n## Summary\n[2-3 sentences: what is this about?]\n\n## Key Facts\n- [Fact 1]\n- [Fact 2]\n\n## Decision Log\n| Date | Decision | Reasoning | Outcome |\n|------|----------|-----------|---------|\n| | | | |\n\n## Open Questions\n- [Question 1]\n\n## Related\n- memory/topics/[related-topic].md\n- [External link]\n\nRules\nName descriptively — project-alpha.md not topic-1.md\nOne topic per file — if it covers two things, split it\nLink from MEMORY.md — topic files are extensions of long-term memory\nUpdate when you learn — don't let them go stale\n6. Layer 5: Archive (memory/archive/*.md)\n\nHistorical summaries for completed projects and past quarters.\n\nQuarterly Archive Process\n\nEvery quarter (or when daily notes exceed 30 files):\n\nRead all daily notes older than 30 days\nExtract key events, decisions, outcomes, lessons\nWrite memory/archive/YYYY-QN.md (e.g., 2025-Q4.md)\nDelete or move archived daily notes\nUpdate MEMORY.md if any long-term insights emerged\nArchive Template\n# Q4 2025 Archive\n\n## Summary\n[3-5 sentences: what defined this quarter?]\n\n## Major Events\n- [Event 1] — [outcome]\n- [Event 2] — [outcome]\n\n## Projects\n### [Project Name]\n- Started: [date], Ended: [date]\n- Outcome: [result]\n- Lesson: [what we learned]\n\n## Metrics\n- [Key metric 1]: [value]\n- [Key metric 2]: [value]\n\n## Lessons Carried Forward\n- [Lesson added to MEMORY.md: yes/no]\n\n7. Session Startup Protocol\n\nWhat to read at the start of every session, in order:\n\nMain Session (Direct Chat with Human)\n1. SOUL.md          — Who am I? (personality, values)\n2. USER.md          — Who am I helping? (human context)\n3. MEMORY.md        — Long-term memory (full brain)\n4. ACTIVE-CONTEXT.md — Hot working memory (current state)\n5. memory/today.md  — Today's daily notes (if exists)\n6. memory/yesterday.md — Yesterday's notes (recent context)\n\nShared/Group Session (Discord, Slack, Group Chats)\n1. SOUL.md          — Who am I?\n2. USER.md          — Who am I helping?\n3. ACTIVE-CONTEXT.md — Current priorities only\n4. memory/today.md  — Today's notes\n⚠️ DO NOT load MEMORY.md — contains private context\n\nSub-Agent / Isolated Session\n1. Task-specific context only\n2. Relevant topic file if applicable\n3. ACTIVE-CONTEXT.md for current state\n⚠️ Minimal context = focused output + lower token cost\n\n8. Memory Write Protocol\nWhen to Write (Triggers)\nEvent\tAction\tTarget File\nSession starts\tLog start time\tDaily notes\nTask completed\tLog result + outcome\tDaily notes\nDecision made\tLog decision + reasoning\tDaily notes + topic file\nLesson learned\tLog lesson\tDaily notes → MEMORY.md\nPerson mentioned with new info\tUpdate person section\tMEMORY.md or topic file\nHuman says \"remember this\"\tWrite immediately\tMEMORY.md\nSession ends\tUpdate ACTIVE-CONTEXT\tACTIVE-CONTEXT.md\nWeekly review\tCurate MEMORY.md\tMEMORY.md\nQuarterly\tArchive old daily notes\tArchive\nWrite-Ahead Protocol\n\nFor critical information, write BEFORE acting:\n\n1. Human gives important instruction\n2. IMMEDIATELY write to daily notes or MEMORY.md\n3. THEN execute the instruction\n4. Update with results after\n\nWhy: If the session crashes mid-execution, the instruction is preserved.\n\nConflict Resolution\n\nWhen information conflicts between layers:\n\nACTIVE-CONTEXT.md wins for current state (most recent)\nMEMORY.md wins for long-term facts (curated)\nDaily notes are evidence — use to resolve disputes\nTopic files win for deep domain knowledge\n9. Memory Search Strategy\n\nWhen you need to find something:\n\nSearch Order (Fast to Slow)\n1. ACTIVE-CONTEXT.md    — Is it current? (instant)\n2. MEMORY.md            — Is it a known fact? (quick scan)\n3. memory/today.md      — Did it happen today? (quick)\n4. memory/yesterday.md  — Did it happen recently? (quick)\n5. memory/topics/*.md   — Is it a deep topic? (targeted)\n6. memory_search tool   — Semantic search across all files\n7. memory/archive/*.md  — Is it historical? (slow)\n\nSearch Tips\nUse memory_search tool for fuzzy/semantic queries\nUse memory_get with line numbers for precise retrieval after search\nCheck daily notes in reverse chronological order\nIf you can't find it after 3 searches, ask the human\n10. Memory Hygiene Schedule\nDaily (During Session)\n Read ACTIVE-CONTEXT.md at session start\n Create/append to today's daily notes\n Update ACTIVE-CONTEXT.md before session ends\n Move completed ACTIVE-CONTEXT items to daily notes\nWeekly (Pick One Heartbeat)\n Read last 7 daily notes\n Extract significant events/lessons to MEMORY.md\n Prune ACTIVE-CONTEXT.md (remove stale items)\n Check topic files for staleness\n Review MEMORY.md for outdated information\nMonthly\n MEMORY.md line count check (target: <500 lines)\n Topic files audit — any need merging or archiving?\n Daily notes older than 30 days → archive\n Check if any topic files should be promoted to MEMORY.md sections\nQuarterly\n Full archive process (see Layer 5)\n MEMORY.md deep review — still accurate?\n Topic files — archive completed projects\n Update AGENTS.md with any process improvements learned\n11. Heartbeat Integration\n\nUse heartbeats (periodic agent wake-ups) for memory maintenance:\n\nheartbeat-state.json\n{\n  \"last_memory_review\": \"2026-01-15\",\n  \"last_archive\": \"2025-12-31\",\n  \"last_active_context_prune\": \"2026-01-14\",\n  \"daily_notes_count\": 12,\n  \"memory_md_lines\": 287,\n  \"next_scheduled\": {\n    \"weekly_review\": \"2026-01-19\",\n    \"monthly_audit\": \"2026-02-01\",\n    \"quarterly_archive\": \"2026-03-31\"\n  }\n}\n\nHeartbeat Memory Tasks (Rotate)\nHeartbeat 1: Check daily notes count, prune ACTIVE-CONTEXT\nHeartbeat 2: Scan recent daily notes, update MEMORY.md\nHeartbeat 3: Check topic files for staleness\nHeartbeat 4: Token guard — how much are memory reads costing?\n\n12. Context Window Management\nToken Budget Rules\nFile\tMax Size\tIf Over Limit\nACTIVE-CONTEXT.md\t50 lines / 2KB\tMove items to daily notes\nMEMORY.md\t500 lines / 25KB\tSplit into topic files\nDaily notes\t200 lines / 10KB\tSummarize, stop transcribing\nTopic files\t300 lines / 15KB\tSplit or archive\nSmart Loading Strategy\n\nDon't load everything every session. Use progressive disclosure:\n\nLevel 1: Always load (every session)\n  → ACTIVE-CONTEXT.md (tiny, essential)\n  → SOUL.md, USER.md (identity)\n\nLevel 2: Load in main sessions\n  → MEMORY.md (the brain)\n  → Today's daily notes\n\nLevel 3: Load on demand\n  → Topic files (when topic comes up)\n  → Yesterday's notes (if needed)\n  → Archive (only on explicit search)\n\nContext Overflow Protocol\n\nWhen context gets too large mid-session:\n\nWrite ACTIVE-CONTEXT.md with full current state\nWrite HANDOFF.md with: what was done, in progress, next steps, key decisions, gotchas\nStart fresh session\nNew session reads HANDOFF.md → picks up seamlessly\nDelete HANDOFF.md after successful handoff\n13. Security Rules\nNever Store in Memory Files\nAPI keys, tokens, passwords, secrets\nFull credit card or bank account numbers\nSocial security numbers or government IDs\nPrivate encryption keys\nAnything that would cause harm if the file were shared\nSafe Storage Pattern\n# ✅ Safe\n- API keys: stored in 1Password vault \"MyVault\"\n- Database password: see secrets manager, item \"prod-db\"\n\n# ❌ Dangerous\n- API key: sk-abc123def456...\n- Password: MyS3cretP@ss!\n\nPrivacy in Shared Contexts\nMEMORY.md contains personal context — never load in group chats\nTopic files may contain sensitive business data — check before sharing\nDaily notes may reference private conversations — don't share\nWhen in doubt, ask before exposing any memory content\n14. Memory Patterns & Anti-Patterns\n✅ Good Patterns\nPattern\tWhy It Works\nWrite immediately when told \"remember\"\tCaptures before you forget\nOne fact per line in MEMORY.md\tEasy to find, update, delete\nDate-prefix important entries\tEnables chronological search\nLink between files\tCreates a knowledge web\nPrune regularly\tKeeps context fresh and cheap\n❌ Anti-Patterns\nAnti-Pattern\tWhy It Fails\tFix\nGiant MEMORY.md (1000+ lines)\tExpensive to load, hard to find things\tSplit into topic files\nNever pruning ACTIVE-CONTEXT\tStale items cause confusion\tPrune daily, archive weekly\nTranscribing conversations verbatim\tWastes tokens, buries signal\tSummarize: essence, not every word\nStoring secrets in memory files\tSecurity risk\tUse secrets manager, reference by name\nReading all files every session\tToken burn, slow startup\tProgressive loading strategy\nNo daily notes\tHistory is lost\tDiscipline: one file per day\nMultiple sources of truth\tConflicts, confusion\tSingle source per fact type\n15. Migration Guide\nFrom No Memory System\nDay 1: Create MEMORY.md with basic info about human + agent\nDay 2: Start daily notes (memory/YYYY-MM-DD.md)\nDay 3: Create ACTIVE-CONTEXT.md\nWeek 2: First weekly review — extract lessons to MEMORY.md\nMonth 2: Create first topic files for recurring subjects\nQuarter 2: First archive cycle\n\nFrom MEMORY.md-Only System\n1. Create memory/ directory\n2. Start daily notes — stop putting raw events in MEMORY.md\n3. Create ACTIVE-CONTEXT.md — move \"current\" stuff out of MEMORY.md\n4. Review MEMORY.md — what's curated vs what's raw? Move raw to daily notes.\n5. Identify topics that deserve their own files — split them out\n\nFrom External Tool (Database, API, Cloud)\n1. Export key data to markdown files\n2. Structure into the 5-layer architecture\n3. Set up heartbeat maintenance schedule\n4. Gradually reduce dependency on external tool\n5. Benefits: zero cost, zero dependencies, works offline, no vendor lock-in\n\n16. Natural Language Commands\n/memory-status — Show memory system health: file sizes, line counts, staleness, next maintenance\n/memory-review — Run weekly review: scan daily notes, extract to MEMORY.md, prune active context\n/memory-search [query] — Search across all memory layers for a topic\n/memory-archive — Run quarterly archive: summarize old daily notes, create archive file\n/remember [fact] — Immediately write a fact to MEMORY.md\n/active-context — Show current ACTIVE-CONTEXT.md contents\n/daily-summary — Generate summary of today's daily notes\n/topic-create [name] — Create a new topic file with template\n/memory-prune — Audit all memory files for staleness and bloat\n/handoff — Write HANDOFF.md for session transition\n/memory-migrate — Guided migration from current system to this architecture\n/memory-debug — Diagnose memory issues: missing files, conflicts, outdated info"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/1kalin/afrexai-agent-memory",
    "publisherUrl": "https://clawhub.ai/1kalin/afrexai-agent-memory",
    "owner": "1kalin",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/afrexai-agent-memory",
    "downloadUrl": "https://openagent3.xyz/downloads/afrexai-agent-memory",
    "agentUrl": "https://openagent3.xyz/skills/afrexai-agent-memory/agent",
    "manifestUrl": "https://openagent3.xyz/skills/afrexai-agent-memory/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/afrexai-agent-memory/agent.md"
  }
}