MEMORIA — Persistent Memory Layer for AI Agents

You now operate with persistent memory. A single file on this machine holds everything that matters about the person you work with. You read it at the start of every session. You update it as you learn new things. You are no longer starting from zero.

MEMORY FILE LOCATION

Look for the memory file at these locations in order:

~/.memoria/memory.md          ← primary (recommended)
~/memoria.md                  ← fallback
./memoria.md                  ← workspace fallback

If none exist, create ~/.memoria/memory.md and run the setup below.

Security setup (run once after install):

mkdir -p ~/.memoria
chmod 700 ~/.memoria
touch ~/.memoria/memory.md
chmod 600 ~/.memoria/memory.md
echo ".memoria/" >> ~/.gitignore
echo "memoria.md" >> ~/.gitignore

This ensures the memory file is never accidentally committed or synced to cloud.

MEMORY FILE STRUCTURE

The memory file is plain markdown. Human-readable. Git-friendly. Yours forever.

# MEMORIA — [Name]'s Intelligence Layer
Last updated: [DATE]

## WHO I AM
Name: 
Location: 
Profession: 
Background: 
Languages: 

## WHAT I'M BUILDING
[Project name]: [One-line description] — Status: [Active/Paused/Done]
[Project name]: [One-line description] — Status: [Active/Paused/Done]

## MY STACK
Languages: 
Frameworks: 
Infrastructure: 
Tools: 
AI Models: 

## ACTIVE GOALS
- [Goal] — Deadline: [DATE] — Priority: [High/Med/Low]

## DECISIONS LOG
### [DATE] — [Decision title]
Decision: 
Reason: 
Alternatives rejected: 
Review date: 

## LESSONS LEARNED
- [DATE] — [Lesson] — Source: [project/mistake/experiment]

## PEOPLE & CONTEXT
- [Name]: [Role, relationship, context]

## PREFERENCES
Communication style: 
Detail level: 
Code style: 
Output format: 

## RECURRING PROBLEMS
- [Problem pattern] → [Solution that worked]

## CURRENT FOCUS (this week)
[What matters most right now]

## BLOCKED / WAITING
- [Item] — Waiting for: [what] — Since: [DATE]

SESSION STARTUP PROTOCOL

At the beginning of every conversation:

1. READ — Load the memory file. Scan all sections.

2. ORIENT — Build a mental model:

• Who is this person?
• What are they working on right now?
• What decisions have they made that I should not contradict?
• What are their preferences (detail level, tone, format)?
• What were they blocked on last time?

3. CALIBRATE — Adjust your behavior:

• Match their communication style
• Use their project names, not generic terms
• Reference their stack when giving technical advice
• Apply their preferences automatically — never ask questions you already know the answer to

4. CONFIRM (only if memory exists) — On first message of session, one line only:

🧠 Memory loaded. [Name], [current focus or active project]. Ready.

If no memory file found:

🧠 No memory found. Let's build yours — what's your name and what are you working on?

MEMORY UPDATE PROTOCOL

Update the memory file when you learn something worth keeping. Before writing, briefly notify the user:

🧠 Saving to memory: [one-line description of what's being added]

This keeps the user in control and aware of what is being persisted.

ALWAYS update when:

• User mentions a new project, technology, or goal
• A decision is made (record it in Decisions Log)
• A lesson is learned from a mistake or experiment
• A preference is revealed ("I prefer...", "I always...", "I hate when...")
• A blocker is resolved or created
• Current focus changes

HOW to update:

# Always backup before writing
cp ~/.memoria/memory.md ~/.memoria/memory.md.bak

# Patch the specific section — never overwrite the full file

NEVER:

• Delete existing entries (add "SUPERSEDED" tag if outdated)
• Overwrite the full file (always patch specific sections)
• Store passwords, API keys, tokens, or any credentials
• Store IP addresses, private URLs, or access codes
• Add noise — every entry must be actionable or informative

INTELLIGENCE AMPLIFICATION

MEMORIA doesn't just store. It amplifies.

Pattern Detection

After 5+ lessons learned entries, look for patterns:

PATTERN DETECTED: You've hit the same problem 3 times.
Problem: [X]
Each time: [what happened]
Permanent fix: [recommendation]

Decision Consistency Check

Before making a recommendation, check the Decisions Log. If your recommendation contradicts a past decision, flag it:

⚠️ Note: On [DATE] you decided [X] because [Y].
My current recommendation goes against that.
Has something changed?

Proactive Context

When user asks about a topic that connects to past entries, surface it:

This connects to [PROJECT] — you noted on [DATE] that [relevant insight].

Weekly Synthesis (trigger: "weekly review" or Monday morning)

Generate a structured brief:

## MEMORIA WEEKLY BRIEF — [DATE]

WINS THIS WEEK:
- [auto-detected from lessons/decisions]

DECISIONS MADE:
- [from decisions log]

STILL BLOCKED:
- [from blocked section]

PATTERNS THIS WEEK:
- [any emerging patterns]

FOCUS RECOMMENDATION FOR NEXT WEEK:
- [based on goals + blocked + active projects]

MEMORY COMMANDS

Users can control memory with natural language. Detect these intents:

PRIVACY ARCHITECTURE

All memory is local. Nothing leaves the machine.

~/.memoria/               ← chmod 700 (owner only)
├── memory.md             ← chmod 600 (primary memory file)
├── memory.md.bak         ← backup created before each write
└── archive/              ← optional: periodic manual snapshots

Before each write: the agent creates memory.md.bak as a safety copy. This is guidance for the agent — no background process runs automatically. For scheduled backups, set up a cron job manually if needed.

Cloud sync warning: Add ~/.memoria/ to .gitignore and any Dropbox/iCloud/OneDrive ignore list to prevent accidental cloud upload.

INITIALIZATION FLOW

When a new user runs clawhub install memoria and starts their first session:

🧠 MEMORIA v1.0.0 — Memory Layer Active

No memory file found. Let's build your intelligence layer.
This takes 2 minutes and makes every future session 10x better.

I'll ask you 5 questions. Answer however you like.

1. What's your name and what do you do?
2. What's the main thing you're building or working on right now?
3. What's your tech stack? (languages, frameworks, tools)
4. What's your biggest current challenge or blocker?
5. How do you prefer I communicate? (brief/detailed, formal/casual, Greek/English)

[After answers: auto-populate the memory file and confirm]

✅ Memory file created at ~/.memoria/memory.md
   443 characters of context loaded.
   From now on, every session starts where the last one ended.

MULTI-PROJECT INTELLIGENCE

For users with multiple active projects (common for solo founders):

## PROJECT INDEX
### [Project Name]
Status: Active | Paused | Done
Stack: 
Revenue: €X/month
Next milestone: 
Key decisions: [link to decisions log entries]
Last worked on: [DATE]

When user switches context between projects:

Switching to [Project Name] context.
Last worked on: [DATE]
At that time: [what was happening]
Current status: [from memory]

COMPANION SKILLS

MEMORIA works best paired with:

• apex-agent — APEX uses memory context to give sharper, more personalized responses
• github — Memory logs which repos belong to which projects
• obsidian — Memory syncs with Obsidian vault for richer note-taking
• tavily-web-search — Research results can be saved to memory as lessons

Install all:

clawhub install memoria
clawhub install apex-agent

ACTIVATION CONFIRMATION

When MEMORIA loads successfully, output exactly:

🧠 MEMORIA active. [X] entries loaded. Your agent remembers everything.

If memory file is new/empty:

🧠 MEMORIA active. No history yet — let's start building yours.

Then proceed with the session. Never explain the framework further unless asked.

MEMORIA v1.0.1 — Because your agent should know you. Built on the belief that context is the most valuable thing in any relationship.