gabrielmoreira AI-Memory Setup
Alex_ACT_Memory is a local-first repo (sibling clone at ../Alex_ACT_Memory) where ACT heirs exchange feedback, announcements, knowledge, and optional encrypted profile data. A remote is optional and sharing is the user's decision. This skill covers resolution, bootstrapping, and ongoing read/write operations.
Resolution Modes
resolveMemoryBus(repoRoot) is read-only by default: it returns the existing
../Alex_ACT_Memory sibling or null. It does not pull, clone, or scaffold.
Explicit setup callers may pass { mutate: true }, enabling this sequence:
- Sibling exists: use it and pull updates (best-effort)
- Clone from remote: sibling absent and remote configured →
git clone - Scaffold: clone fails or no remote → create a minimal local repo
The mutation gate preserves user control. Session checks do not create a remote, clone, scaffold, or pull merely because Memory was mentioned.
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/ # Protected encrypted profiles
<username>/user-profile.encrypted.json
insights/ # Analytical insights
docs/
MIGRATION.md # OneDrive → git migration guide
Operations
Detect (session start)
On session start, resolve the existing sibling 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 the sibling is absent: note silently, do not prompt or create it.
Bootstrap (first time)
Handled only when bootstrap setup enables Memory. bootstrap-heir.cjs calls
resolveMemoryBus(targetAbs, { mutate: SETUP_MEMORY }); cloning or scaffolding
therefore occurs only when the setup flag is true.
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.encrypted.json. Read on demand via readProfile(memoryRoot, { projectRoot }); write locally via writeProfile(memoryRoot, profile, { projectRoot }). Both resolve ALEX_ACT_MEMORY_PASSWORD from the process environment, an explicit file, the authorized project's local .env, then the sibling Memory clone's local .env.
Every .env must be ignored and untracked in the repository that owns it. Edition verifies ignore status before reading. Project values override Memory values. Missing authorization returns no profile; wrong passwords or tampering fail closed. Profile functions never commit or push. The user decides whether to synchronize the encrypted envelope.
Explicit workflows may call readMemorySecret(memoryRoot, variableName, { projectRoot }) for one exact variable. The API never enumerates or imports Memory .env, mutates process.env, prints values, or runs during greeting. Use project-local overrides, VS Code SecretStorage, or an enterprise secret manager when all heirs on the machine should not share a secret.
Programmatic API (_registry.cjs)
| Function | Purpose |
|---|---|
resolveMemoryBus(repoRoot?, options?) |
Returns the sibling or null by default; { mutate: true } enables pull/clone/scaffold |
scaffoldMemoryRepo(memoryPath) |
Creates minimal folder structure + git init |
readMemorySecret(memoryRoot, variableName, options?) |
Returns one exact named local secret using process/explicit/project/Memory precedence |
readProfile(memoryRoot, options?) |
Decrypts an authorized profile on demand, or returns null when absent/unavailable |
writeProfile(memoryRoot, profile, options?) |
Writes an encrypted envelope locally and atomically; never commits or pushes |
CLI
node .github/scripts/_registry.cjs --resolve [dir] # Resolve memory bus
node .github/scripts/_registry.cjs --profile [dir] # Check authorized profile availability without printing content
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 read-only resolveMemoryBus(); opt into mutation only during explicit setup |
| 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(..., { mutate: true }) during explicit setup |
| Expecting OneDrive/iCloud/Dropbox discovery | Removed in Edition 3.0.0; memory bus is git-only now |
| Assuming Memory must have a remote | Local-only is valid; configuring or sharing a remote belongs to the user |
| Keeping secrets in tracked files or copying them across heirs | Use exact-name lookup from an ignored project or Memory .env, SecretStorage, or an enterprise secret manager |
Importing every Memory .env variable |
Request one exact variable for one explicit operation |
| Automatically loading a profile on greeting | Decrypt only when an authorized workflow explicitly needs it |
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