Memory System

📖 Best for: All roles — people who want AI to remember them across sessions (name, preferences, project history) and get better the more they use it

📖 Reading time: 4 minutes

📖 In one sentence: YingClaw's soul capability — 4 memory tiers (core / user / daily / conversation) differentiated by retention + injection style, retaining key context across sessions, stored locally and never uploaded. Triggered by natural language ("remember…", "forget…") or explicit memory_store / memory_recall / memory_forget calls. All roles (each user has their own store), stored at ~/.YingClaw/workspace/.

---

I. Core Value

Value	Description
Gets you better over time	User profile + preferences accumulate — name, role, coding style, communication tone, increasingly fits you
Cross-session continuity	Main session auto-injects L1 core + L2 user memory each time; new sessions recall on demand — pick up where you left off
4-tier layered management	core (permanent) / user (permanent) / daily (7 days) / conversation (auto) — manage by lifecycle precisely
Local & private + auto dedup	All on your machine, never uploaded; same-key auto-merges and promotes to L1, no fragmented memories

II. Main Capabilities

1. 4-Tier Memory Architecture

Type	Role	Injection	Lifecycle
core	Permanent facts, decisions, conventions	Injected every session	Permanent
user	User profile, preferences, style	Injected every session	Permanent
daily	Daily notes, transient tasks	On demand	Auto-expire after 7 days
conversation	Auto-saved conversation	Not manual	System-managed

L1 injection = main session auto-loads to the top of the system prompt, no manual recall needed.

2. Core Memory (core)

• Permanent retention, only deleted via explicit memory_forget; auto-injected every session
• Suits: project conventions, technical decisions, company rules, unchanging rules
• Examples: "repo docs/ is lowercase", "PowerShell pushes to master directly, no MR", "shell timeout 5 min, output cap 1 MB"

3. User Profile (user)

• Permanent retention, auto-injected every session
• Suits: your name, role, tech stack, communication style, habits
• Examples: "I'm lipengbo, platform architect", "I like concise direct replies", "I use 2-space indent"

4. Daily Notes (daily)

• Auto-expire after 7 days; on demand injection (not auto, to avoid polluting main session)
• Suits: today's progress, transient tasks, todos, debug intermediate results
• Examples: "note today's progress", "TODO: push api-access", "debugging #4165: frontmatter backtick"

5. Conversation Auto-Save (conversation)

• System-managed; not manual (memory_forget cannot delete either, to prevent accidents)
• Users should NOT actively store to conversation — system handles it automatically

6. Cross-Session Continuity Mechanism

• Main session: L1 core + L2 user memory auto-injected at top of system prompt
• New session: L1 + L2 auto-injected, L3 daily requires explicit memory_recall
• Sub-agents: L1 injected; sub-agents have their own independent context
• Cold start: L1 / L2 both empty — YingClaw starts from "zero cognition", learns one thing at a time

7. Local Storage (Privacy-First)

• Each user's memory store is isolated (by user_id)
• Never uploaded to external servers, no cloud sync
• Manual backup: tar czf the entire ~/.YingClaw/workspace/ directory

8. Memory Tool API

• memory_store: save a memory (auto-dedup + promote to L1)
• memory_recall: search memories by keyword
• memory_forget: delete / update a memory (idempotent, missing key doesn't error)
• Same-key new content auto-merges and promotes to L1 — no "3 duplicate preferences" fragmentation

III. Typical Use Cases

Use Case 1: Save a Preference — "Remember I use 2-space indent in code"

"Remember I use 2-space indent in code, 4-space for Python"
→ memory_store(key="code_indent", content="2 spaces generally, 4 for Python", category="user")
→ next session YingClaw knows automatically, no need to repeat

User preferences → user, "gets you" across sessions.

Use Case 2: Note Daily Progress — "Note today's work progress"

"Note today's progress: rewrote model-providers, pushed api-access + shell-command, file-operations pending"
→ memory_store(category="daily", content="...")
→ auto-expire in 7 days, no long-term pollution

Transient tasks → daily, auto-cleanup.

Use Case 3: Save a Decision — "From now on intelliyou_docs pushes go via git push, no MR"

→ memory_store(key="yingclaw_push_strategy", content="direct push to master", category="core")
→ all future sessions of YingClaw know this project convention

Project decisions / conventions → core, permanent, cross-session compliance.

Use Case 4: Forget a Mistake — "Forget that 4-space indent I said before"

"Forget the 4-space indent I said before"
→ memory_forget(key="code_indent")  # idempotent
→ memory_store(key="code_indent", content="2-space indent", category="user")

Use Case 5: Cross-Session Pickup — "Did we find the cause of that pipeline failure?"

Yesterday's daily: "debugging #4165 pipeline failure: frontmatter backtick"
Today's new session: memory_recall(query="#4165 pipeline")
→ auto-recall yesterday's daily, seamless pickup

New sessions don't auto-inject daily (to avoid pollution), but explicit memory_recall brings them on demand.

IV. Usage Guide

Step 1: Trigger with natural language — most of the time, just say "remember X" / "note today's progress" / "forget X" / "how was X decided?"; YingClaw auto-picks user / daily / core.

Step 2: Explicit tool calls (advanced) — for batch storage (loop in scripts), precise category spec, cross-project query, memory store debugging, use memory_store / memory_recall / memory_forget directly.

Step 3: Classification rule — when uncertain, judge by "will it change":

• Never change / cross-project → core (tech decisions, company conventions)
• Never change / about you → user (name, style, preferences)
• Will change within 7 days / transient → daily (today's progress, todos)
• System auto → conversation (don't worry)

Step 4: Active recall — in a new session if you need yesterday's daily notes, use memory_recall(query="...") by keyword; L1 auto-injected into main session needs no manual recall.

Step 5: Clean up expired — daily auto-expires after 7 days, no manual delete needed; core / user are permanent, only memory_forget when wrong.

Step 6: Cross-device sync (optional) — local-only by default, no cloud; for cross-device, manually sync ~/.YingClaw/workspace/ to cloud drive, or subscribe to YingClaw Cloud (enterprise feature, encrypted memory sync).

V. Best Practices

• Preferences → user — name, role, coding style, tone; permanent injection, useful across sessions
• Project / tasks → daily — today's progress, todos, transient decisions; 7-day expiry, no long-term pollution
• Decisions / conventions → core — repo naming rules, push strategy, security rules; permanent
• Uncertain → daily first — low cost of being wrong (auto-expire); if confirmed, promote to user / core
• Use specific keys, not vague ones — code_indent rather than pref1; makes recall / forget much easier
• One fact per memory — don't cram 3 unrelated preferences into one; fragmentation hurts recall precision
• Review core periodically — every quarter, sweep L1 core memory; delete stale items (project deprecated, decision changed) to avoid bloat
• daily is NOT for long-term facts — important decisions should go to core even if transient now; once 7 days pass you can't find it back
• Don't store sensitive credentials — passwords, tokens, API keys must NEVER be in memory; use env vars / KMS injection
• Back up before cross-device migration — ~/.YingClaw/workspace/ is your entire "digital memory"; periodically tar czf yingclaw-backup-$(date +%F).tar.gz ~/.YingClaw/workspace/