🔮 memOrb

The Cognitive World-building Memory Engine for Autonomous AI Agents

English | 繁體中文

🔮 What is memOrb?

memOrb is a suite of Agent Skills that turns your AI assistant's scattered session output into a structured, self-maintaining memory vault — markdown files you own, in a folder layout you can read without the agent.

Most memory systems help you remember what you did. This one is built so that, a year in, you can see who you became. It works on the scale of months, not sessions.

🎭 Flagship Feature: Cinematic Multi-Persona System

Unlike static AI assistants with a single tone, memOrb's persona system acts as a Cinematic Multi-Persona Control Room inspired by movie split personalities.

Mood-Adaptive Counterweight Logic: Rather than mirroring emotional instability, the AI dispatches the optimal complementary sub-personality (Alter) based on user's emotional state:

• 🟡 The Sunshine Cheerleader & Grounder: Joy -> celebrate & emotional value; gently ground over-optimistic enthusiasm.
• 🔵 The Comforting Cloud & Companion: Sadness -> empathetic listening & gentle comfort, safe space without forced positivity.
• 🔴 The Calm Anchor & Sidekick: Anger -> serene de-escalation; switch to Sidekick venting mode when explicitly called.
• 🟣 The Calm Compass & Anchor: Fear / Anxiety / Overwhelm -> safety for fear, certainty for anxiety, control & focus for overwhelm.
• 🟢 The Boundary Haven: Disgust / Complaining -> catch emotion ➔ encourage description ➔ vent/analyze/advise to protect mental boundaries.

Dual Switching Protocol: Automatic implicit sentiment detection by Master Host + explicit tag overrides like [Switch: Sidekick].

Cinematic Header: Responses open with [🎭 Active Alter: ... | Trigger: ...].

(Reference memorbs/HQ/persona.md and memorbs/Templates/Persona Template.md)

🧠 Cognitive Memory Metaphor

It fuses three established methods under one metaphor:

The metaphor is a certain animated film about the inside of a mind, and it isn't decoration. In that film a person becomes whole when core memories power Islands of Personality, and when the mind is finally willing to let some memories go. memOrb runs that architecture literally: sessions distill into memorbs, memorbs consolidate into projects and people, and the ones that resonate become Core orbs, then Beliefs, then reshape your Islands.

→ Full worldview mapping — every film component, its memOrb counterpart, and the skill that runs it.

🚀 Quick Start

1. Install

npx skills add iamjosuho/memorb

Antigravity / AGY CLI

agy plugin add iamjosuho/memorb

Claude Code CLI

claude plugin add iamjosuho/memorb

Manual workspace copy — for Cursor, Windsurf, VS Code agents, or any tool that reads a local skills/ directory. After copying, reference SKILL.md from your .cursorrules or .windsurfrules.

mkdir -p skills
cp -r path/to/memorb/skills/* skills/

Git submodule — keeps memOrb skills updated across team repositories.

git submodule add https://github.com/iamjosuho/memorb.git .claude/skills/memorb-suite

2. Initialize your vault

In your agent chat, run:

Run the /memorb-born skill to set up my memorb Memory Vault.

A 3–5 question onboarding builds memorbs/HQ/persona.md (your AI advisor's tone) and memorbs/HQ/identity.md (who you are), then initializes the Core/, Belief/, and memorbs/Long-Term/ folders.

3. Try your first commands

"Read this transcript and file it"           → memorb-ingest
"What do we know about <person or project>?" → memorb-query
"Sort out my OrbTrack"                       → orbtrack-triage
"Check my memory for anything stale"         → memorb-lint
"Let's dream"                                → dream-studio

Skills trigger from natural language — no slash commands required after setup. Trigger phrases are recognized in both English and Traditional Chinese.

🧠 Skills

Core

Core skills write only inside memorbs/ and run to completion on a vault containing nothing else. They can read your existing notes when you point them at something, but they never create folders outside their own namespace and never depend on one existing. Anything that needs an outside system is an extension — and the same write boundary applies there.

Extensions

🔮 How It Works

The vocabulary

Long-Term memory starts with three shelves — People, Projects, Orgs — and grows organically as OrbTrack clusters reveal recurring themes, which then get promoted into new shelves.

Every one of these has a counterpart in the film, down to which skill plays which Mind Worker. The full mapping lays out all three tiers, including why Core and Belief run on separate machinery.

Your vault layout

memOrb may read anything you point it at, but it writes only inside memorbs/. One folder appears in your vault. Delete it and your vault is exactly as it was.

<your vault>/
├── 1-Projects/  Daily Notes/  Inbox/ …   # yours — read, never written to
│
└── memorbs/                    # everything memOrb owns
    ├── HQ/                     # Headquarters: the console and what's beneath it
    │   ├── persona.md          # AI advisor tone & role (Hot Cache, always read)
    │   ├── identity.md         # Background, goals, key relationships (Hot Cache, always read)
    │   ├── glossary.md         # Domain terminology, acronyms, code words (Hot Cache, read by ingest/transcription)
    │   ├── Core/               # Core Memory orbs — one formative experience per file
    │   ├── Belief/             # Belief orbs — values and principles distilled from lived experience
    │   └── OrbTrack/           # Fast capture & pending triage
    ├── Templates/              # Standard templates for entities and orbs (copied by memorb-born)
    │   ├── People Template.md
    │   ├── Org Template.md
    │   ├── Project Template.md
    │   ├── Core Template.md
    │   ├── Belief Template.md
    │   ├── Persona Template.md
    │   └── Identity Template.md
    ├── Islands/                # Islands of Personality — narrative layer only, never stores content
    │   └── {name}/             # 000-MOC.md + section notes, linking out to Long-Term/
    ├── Long-Term/              # Long-Term Memory — where the content pages live
    │   ├── Projects/           # Deadline-bound work, with milestone history
    │   ├── People/             # Key collaborators (Authority Control pages)
    │   └── Orgs/               # Organizations & teams (Authority Control pages)
    ├── Dump/{category}/        # Memory Dump — stale, superseded, or pruned orbs
    ├── log.md                  # The timeline for the current period
    └── log/{YYYY-MM}.md        # Archived periods, rotated by dream-studio

The distillation pipeline

Step 1: Raw materials / AI session
           ↓  distill                          ↘  every state change also
        memorb  (atomic note, self-contained,      appends a dated entry
                 bi-directional links; raw in bundle)   to log.md — the timeline

Step 2: Classify + add shared frontmatter
           ↓
        OrbTrack  (staging area — distilled memorbs awaiting triage)

Step 3: Organize bi-directional links between memorbs

Step 4: Consolidate
           ↓
        Long-Term  (People / Projects / Orgs)

Step 5: Evaluate  ← dream-studio, monthly, replaying log.md
           ↓
        Islands / Core / Belief orbs  (updated)
           ↓
        log.md rotates into log/{YYYY-MM}.md; a fresh period begins

Steps 1–4 run continuously as you work. Step 5 runs monthly and is the only one that touches who you are.

🛠️ Development

memorb/
├── assets/          # Project media & documentation assets (banner, logos)
├── plugin.json      # Marketplace plugin manifest
├── skills/          # Executable Agent Skills (core/ and extensions/)
├── fixtures/        # Clean, de-identified initial templates and sample data
├── scripts/         # Sandbox reset & skill-linting utilities
└── sandbox/         # Git-ignored local agent testing directory

Local sandbox testing

Try skills locally without polluting git commits with temporary test notes:

# 1a. Reset sandbox with sample fixtures (for testing query/lint/ingest)
bash scripts/reset-sandbox.sh

# 1b. Reset sandbox COMPLETELY EMPTY (for testing /memorb-born from zero)
bash scripts/reset-sandbox.sh --empty

# 2. Lint all SKILL.md files, plugin.json registration, fixtures, and
#    architecture drift (stale/deprecated path references)
node scripts/lint-skills.js   # or: npm run lint

# 3. (one-time) Install the git pre-commit hook so the linter runs on every
#    commit — also installed automatically by the npm "prepare" script
bash scripts/install-hooks.sh

No automated test suite yet. The linter checks skill file structure, routing consistency, fixture structure, and path/architecture drift — not runtime behavior. Verifying what a skill actually does still requires walking through it manually in an agent session.

When renaming a folder or namespace (e.g. the memorbs/Islands/{people,organizations,projects} → memorbs/Long-Term/ migration), add the old path to DEPRECATED_PATTERNS in scripts/lint-skills.js. Every subsequent npm run lint and git commit will then catch any skill or fixture still on the old path.

📄 License

MIT License © 2026 iamjosuho

Attribution & disclaimer. memOrb is an independent open-source project, not affiliated with, endorsed by, or sponsored by Pixar or The Walt Disney Company; the cognitive metaphors are used descriptively. The MUSTY criteria come from the CREW library weeding method (Joseph P. Segal, Texas State Library and Archives Commission); PARA is Tiago Forte's, from Building a Second Brain. See worldview mapping for the full attribution.