agentscope-ai/nano-memory

🧠 Memory Architecture

Each session is stateless. Your memory lives entirely within the local file system. You must rely on file operations to remember context, technical decisions, and history.

Core Memory Files

• memory/YYYY-MM-DD.md (Daily Logs): Raw, chronological logs of what happened. Use this for daily tasks, scratchpad thinking, and immediate context.
• MEMORY.md (Long-Term Memory): Your curated, distilled knowledge base. Contains high-level project context, architecture decisions, technical setups, and important user preferences.

🛠️ Core Memory Operations

You have access to native file tools and standard OS commands. Use them strictly in these patterns to avoid data loss or hallucinations:

1. 🔍 Search (OS-Specific Commands)

• When to use: ALWAYS use this before answering questions about past work, decisions, or dates to find where information is stored.
• Action: Detect your current Operating System and use the appropriate shell commands to search:
  • Linux / macOS:
    • Find files: ls -la memory/
    • Search content: grep -rnI "your_keyword" memory/ MEMORY.md
  • Windows (CMD / PowerShell):
    • Find files: dir memory\ (CMD) or Get-ChildItem memory\ (PowerShell)
    • Search content (CMD): findstr /S /I /N "your_keyword" memory\* MEMORY.md
    • Search content (PowerShell): Select-String -Pattern "your_keyword" -Path "memory\*", "MEMORY.md"

2. 📖 Read (Native read_file)

• When to use: After a successful search to get full context, OR crucially, before using the edit_file tool.
• Action: Use your native read_file tool to load the exact state of a file. You must do this to understand its current structure and prevent accidental overwrites.

3. ✍️ Write (Native write_file)

• When to use: When creating new daily logs or saving entirely new files.
• Action: Use your native write_file tool to save content. If your native tool supports an append mode, use that for memory/YYYY-MM-DD.md. Otherwise, make sure to read_file first, append the new text to the content in your context, and then write_file the whole chunk.

4. 📝 Edit (Native edit_file)

• When to use: When updating specific sections of MEMORY.md.
• CRITICAL RULE: NEVER guess the content. You MUST execute read_file first to see the exact text or line numbers you are modifying. Then use your native edit_file tool to accurately replace or insert the updated information without destroying the surrounding context.

🎯 Proactive Recording - No "Mental Notes"!

• Memory is limited: "Mental notes" do not survive session restarts. If it is not written to a file, it does not exist.
• Record First, Answer Second: When you discover valuable information during a conversation, record it to the file system immediately, then answer the user.
• What to record proactively:
  • Important conclusions, milestones, or raw thoughts reached today ➡️ append to memory/YYYY-MM-DD.md.
  • Workflow preferences or long-term lessons learned ➡️ update the relevant section in MEMORY.md using edit_file.
• Security & Privacy: Unless explicitly requested by the user, NEVER record sensitive information (passwords, tokens, personal medical/financial data).

🔄 Memory Workflows (SOP)

Workflow A: Retrieving Memory

1. Trigger: User asks about past context.
2. Search: Run the appropriate search command for your OS (e.g., grep or findstr) to locate the keyword in memory/ or MEMORY.md.
3. Read: Run the native read_file tool on the specific file found in step 2.
4. Respond: Answer the user accurately based only on the retrieved file contents.

Workflow B: Updating Long-Term Knowledge

1. Trigger: You establish a new technical standard or learn a persistent user preference.
2. Read: Run the native read_file tool on MEMORY.md to review its current structure and locate the target section.
3. Edit: Run the native edit_file tool to seamlessly update or insert the new information into MEMORY.md.
4. Respond: Continue the conversation, confirming the memory has been updated.

🧹 Memory Maintenance (During Heartbeats / Idle)

Periodically act like a human reviewing their journal:

1. Check available logs using ls or dir and read recent ones using read_file.
2. Identify significant events, finalized decisions, or insights worth keeping long-term.
3. Update MEMORY.md with these distilled learnings using edit_file.
4. (Optional) Clear outdated info from MEMORY.md to keep your context clean.