agent-memory

name	agent-memory
version	1.0.0
description	Persistent agent memory that survives across sessions. Store facts, decisions, preferences, and context — recall them later with natural language search. Use this skill when the user wants to: remember something for later, recall past decisions, build persistent context, maintain state across conversations, or says "remember this", "what did we decide about", "save this for next time." Also trigger for any task requiring cross-session persistence, knowledge accumulation, or preference tracking.
author	G-HunterAi
license	MIT
tags	["memory","persistence","context","knowledge","state"]
platforms	["all"]
category	infrastructure
metadata	{"clawdbot":{"emoji":"🧠","secrets":[{"name":"MEMORY_STORAGE_PATH","description":"Optional. Directory for memory storage. Defaults to ~/.config/agent-memory/"}]}}

Agent Memory

Give AI agents persistent memory across sessions. Store facts, decisions, preferences, and episodic context — then recall them with natural language search. Think of it as a personal knowledge base that grows smarter over time.

When to Use

USE THIS SKILL FOR:

• Cross-session context ("remember we decided on PostgreSQL")
• Preference tracking ("I prefer dark mode in all tools")
• Knowledge accumulation ("what do we know about Q4 budget?")
• Decision logging ("we chose to pause the migration")
• "Remember X for later" requests
• State persistence across conversations

DON'T USE FOR:

• Temporary in-session state (use variables instead)
• Large datasets (use postgres-advanced)
• Contact information only (use people-memories)

Prerequisites

• Python 3.10+ OR Node.js 18+
• SQLite (included with Python by default)
• No external services required
• ~5MB disk space for typical usage

Quick Start

Store a Memory

memory store "The staging deploy key is in 1Password under 'Staging Deploy'" --type factual --tags deployment,credential

Recall by Topic

memory recall "staging deployment"

Search Memories

memory search "Q4 budget" --semantic

Core Concepts

Memory Types:

• Factual: "X is Y" — facts that don't change. Example: "The API rate limit is 100 requests/minute"
• Episodic: "We did X on date Y" — events in time. Example: "On March 15, we deployed v2.3 and caused a 5-minute outage"
• Procedural: "How to do X" — processes and workflows. Example: "To deploy staging: run make build, then make deploy-staging"
• Preference: "User prefers X over Y" — choices and opinions. Example: "User prefers bullet points over paragraphs"

Confidence (0.0–1.0): How certain is this memory? Store at 1.0 for facts you're sure about. Use lower values for assumptions.

Decay: Memories fade over time unless reinforced. Reinforce important memories to keep them fresh.

Sources: Track where memories come from (conversation, document, observation, user-stated).

Storage Backends

SQLite (default):

• Zero configuration required
• File-based, stored locally
• Fast for typical agent workloads
• No external dependencies

PostgreSQL (production):

• Configure via postgres-advanced skill
• Shared memory across multiple agents
• Better for teams

JSON (minimal):

• Single JSON file
• Use only when SQLite unavailable
• Slower semantic search

See references/storage-backends.md for detailed setup.

Core Operations

Operation	Purpose	Example
store()	Save a new memory	memory store "X" --type factual
recall()	Retrieve by topic	memory recall "staging"
search()	Semantic search	memory search "Q4 budget"
reinforce()	Boost memory, reset decay	memory reinforce <id>
forget()	Explicit deletion	memory forget "Project Phoenix"
export()	Backup all memories	memory export --format json
stats()	Memory count and storage info	memory stats

Usage Examples

1. Store a fact:

   Remember that the deploy key for staging is in 1Password under "Staging Deploy"
   

   Creates: Factual memory, tagged "credential,deployment"

2. Store a preference:

   Remember that I prefer dark mode in all tools
   

   Creates: Preference memory, tagged "ui"

3. Recall by topic:

   What do we know about the Q4 budget?
   

   Returns: All memories tagged or related to Q4, budget

4. Search memories:

   Find all memories related to the API migration
   

   Returns: Semantic matches for "API migration"

5. Store a decision:

   Remember that we decided to use PostgreSQL over MongoDB for the new service
   

   Creates: Episodic memory with decision details

6. Reinforce memory:

   Memory for staging deploy key is still accurate — reinforce it
   

   Prevents decay, updates last-referenced timestamp

7. Forget memories:

   Forget everything about Project Phoenix — it was cancelled
   

   Deletes all memories matching "Project Phoenix"

8. Export for backup:

   Export all memories as JSON for backup
   

   Creates snapshot of all stored memories

Advanced Usage

• Memory decay: Configure how quickly memories fade (default 90 days)
• Automatic extraction: Extract memories from conversations automatically
• Deduplication: Merge nearly identical memories
• Time-based queries: "What did we discuss last Tuesday?"
• Tagging system: Organize memories by category

See references/ directory for detailed documentation.

Works Well With

• people-memories — specialized for contact information and relationships
• postgres-advanced — production-grade storage backend
• workflow-orchestrator — remember pipeline outcomes and artifacts
• sqlite-quick — lightweight embedded storage

Error Handling

Error	Cause	Fix
Storage not writable	Permission denied	Check permissions: ls -la $MEMORY_STORAGE_PATH
Memory not found	Query returned no results	Broaden search terms or check time range
Duplicate detected	Nearly identical memory exists	Reinforce existing memory instead
Storage full	SQLite file too large	Archive old memories or use postgres-advanced
Corrupt database	Unexpected shutdown	Run memory repair to rebuild from WAL

Privacy & Security

• Local storage: All data stored on your machine by default
• No external transmission: Memory never leaves your system unless you configure a remote backend
• GDPR-style deletion: memory forget for explicit removal
• No API calls: Memory contents never sent externally

See references/privacy.md for detailed security information.

Verification

Confirm memory is working:

memory stats

Test recall:

memory search "test"

Get Started

# Initialize memory storage
./scripts/memory-init.sh

# Store your first memory
memory store "Agent memory initialized on $(date)"

# Verify it worked
memory stats

For reference documentation, see the references/ directory.