fabioc-aloha AI-Memory Setup
Alex_ACT_Memory is a shared git repo (sibling clone at ../Alex_ACT_Memory) where ACT heirs exchange feedback, announcements, knowledge, and profile data. This skill covers resolution, bootstrapping, and ongoing read/write operations.
Resolution Algorithm (3-state)
The _registry.cjs script resolves the memory bus in this order:
- Sibling exists:
../Alex_ACT_Memory/.gitis present → use it, pull updates (best-effort) - Clone from remote: sibling absent, remote URL configured →
git clone - Scaffold: clone fails or no remote → create minimal local repo
Resolution always succeeds (scaffold is the floor). Heirs never need to configure cloud drives or pin paths.
Folder Structure
../Alex_ACT_Memory/
README.md
announcements/ # Fleet-wide release notes and guidance
README.md
feedback/ # Heir friction reports
README.md
knowledge/ # Shared knowledge packages
index.json
README.md
profile/ # Per-user profiles
default/README.md
<username>/user-profile.json
insights/ # Analytical insights
docs/
MIGRATION.md # OneDrive → git migration guide
Operations
Detect (session start)
On every session start, resolve the memory bus via resolveMemoryBus(repoRoot). If found:
- Check
announcements/for unread files - Report any new announcements to the user (one line each)
- Do NOT read or report feedback (that's the Supervisor's job)
If resolution fails completely (should not happen — scaffold is the floor): note silently, do not prompt.
Bootstrap (first time)
Handled automatically by bootstrap-heir.cjs. The script calls resolveMemoryBus(targetAbs) which clones or scaffolds as needed. No user interaction required.
To manually resolve:
node .github/scripts/_registry.cjs --resolve .
Write Feedback
When the heir observes friction worth surfacing:
- Resolve memory bus
- Write one markdown file to
feedback/ - Filename format:
YYYY-MM-DD-<heir-id>-<short-slug>.md - Strip project specifics per
cross-project-isolation.instructions.md - Commit and push (best-effort; push may fail without remote)
Read Announcements
On session start (triggered by greeting-checkin.instructions.md):
- Resolve memory bus
- List files in
announcements/(skip README.md) - For each unread file, report the title and date
- Do NOT delete announcement files (they persist for all heirs)
Profile
User profiles live at profile/<username>/user-profile.json. Read via readProfile(memoryRoot), write via writeProfile(memoryRoot, profile).
Programmatic API (_registry.cjs)
| Function | Purpose |
|---|---|
resolveMemoryBus(repoRoot?) |
Returns { root, level, message } — always succeeds |
scaffoldMemoryRepo(memoryPath) |
Creates minimal folder structure + git init |
readProfile(memoryRoot) |
Returns user profile object or null |
writeProfile(memoryRoot, profile) |
Writes profile + best-effort commit/push |
CLI
node .github/scripts/_registry.cjs --resolve [dir] # Resolve memory bus
node .github/scripts/_registry.cjs --profile [dir] # Read user profile
Migration from OneDrive-based AI-Memory
Users upgrading from Edition <3.0.0 need a one-time migration:
- Clone
Alex_ACT_Memoryas a sibling:git clone https://github.com/fabioc-aloha/Alex_ACT_Memory.git ../Alex_ACT_Memory - Copy content from old
<cloud-drive>/AI-Memory/to the new repo - Remove
ai_memory_rootandai_memory_excludefromcognitive-config.json - Full guide:
../Alex_ACT_Memory/docs/MIGRATION.md
Anti-Patterns
| Anti-pattern | Correction |
|---|---|
| Hardcoding an absolute path to memory | Use resolveMemoryBus() — it handles all three states |
| Writing feedback without stripping project context | Always apply cross-project-isolation before writing |
| Reading feedback as a heir | Feedback is for the Supervisor; heirs read announcements only |
Calling scaffoldMemoryRepo directly |
Use resolveMemoryBus() which handles the full fallback chain |
| Expecting OneDrive/iCloud/Dropbox discovery | Removed in Edition 3.0.0; memory bus is git-only now |
Falsifiability
- This skill has failed if heirs report memory bus resolution errors within 30 days of following the setup procedure
- The 3-state algorithm is wrong if
scaffoldMemoryRepoproduces repos that can't later accept a remote and sync - The bootstrap sequence is stale if
_registry.cjsexports change and this skill references obsolete functions