[FEAT] user-level memory layer (v3.0.0)

CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## v3.0.0
+
+### Added
+- User-level memory layer at `~/.orrery/user/memory/`. Cross-project, cross-env
+  personal memory served via:
+  - SessionStart hooks installed automatically into each env's Claude / Codex /
+    Gemini config (controlled by per-env `shareUserMemory`, default enabled).
+  - MCP tools `orrery_user_memory_read` and `orrery_user_memory_write`.
+  - New CLI subcommands `orrery memory user info / path / emit / export /
+    enable / disable`.
+- Wizard question on env creation: "Enable user memory?" (default: yes).
+- `--no-user-memory` flag on `orrery create` to opt out from the CLI.
+
+### Changed
+- **BREAKING:** `orrery memory <info|export|isolate|share|storage>` renamed to
+  `orrery memory project <info|export|isolate|share|storage>`. No aliases.
+  Scripts must be updated.
+- Interactive `orrery memory` now lists both project and user memory states and
+  routes into the relevant submenu.
+
+### Internal
+- Introduced `MemoryStore` value type to share read/write/fragment logic
+  between project- and user-level memory.
+- New `UserMemoryHookInstaller` protocol with Claude / Codex / Gemini
+  implementations; internal `_reconcile-user-memory-hooks` command runs on
+  every `orrery use`.
+
+### Notes
+- Existing memories under `~/.orrery/shared/memory/{projectKey}/` are
+  untouched.
+- A future `orrery memory user import` will help lift cross-project entries
+  out of the project layer; not in this release.
+- If you use `orrery-sync`, add `~/.orrery/user/memory/fragments/` to your
+  watched-paths list to enable cross-machine sync of user memory. The fragment
+  format is identical to the project layer.
+
 ## v2.7.0 - 2026-04-29
 
 ### Architecture

Sources/OrreryCore/Commands/CreateCommand.swift

@@ -29,6 +29,9 @@ public struct CreateCommand: ParsableCommand {
     @Flag(name: .long, help: ArgumentHelp(L10n.Create.isolateMemoryHelp))
     public var isolateMemory: Bool = false
 
+    @Flag(name: .long, inversion: .prefixedNo, help: ArgumentHelp(L10n.Create.userMemoryDisableHelp))
+    public var userMemory: Bool = true
+
     public init() {}
 
     public func run() throws {
@@ -49,6 +52,7 @@ public struct CreateCommand: ParsableCommand {
         //   "yes"). Same per-step flag overrides apply.
         var configs: [ToolSetupRunner.Config]
         var installStatusline = false
+        let shareUserMemoryDefault: Bool
         if let toolFlag = tool {
             guard let t = Tool(rawValue: toolFlag) else {
                 throw ValidationError(L10n.Create.unknownTool(toolFlag))
@@ -61,8 +65,17 @@ public struct CreateCommand: ParsableCommand {
                 isolateSessionsOverride: isolateSessions,
                 isolateMemoryOverride: isolateMemory
             )]
+            // Explicit-tool path skips the interactive wizard, so the user-memory
+            // preference comes from the (default-true) --user-memory/--no-user-memory flag.
+            shareUserMemoryDefault = userMemory
         } else {
-            (configs, installStatusline) = Self.runWizard(store: store)
+            let wizardResult = Self.runWizard(store: store)
+            configs = wizardResult.0
+            installStatusline = wizardResult.1
+            // --no-user-memory takes precedence over the wizard answer: if the
+            // user explicitly passed --no-user-memory (userMemory == false),
+            // honor that; otherwise use whatever the wizard returned.
+            shareUserMemoryDefault = userMemory ? wizardResult.2 : false
         }
 
         // Create empty env — per-tool flags populated during apply()
@@ -105,13 +118,23 @@ public struct CreateCommand: ParsableCommand {
                 print("Could not install statusline: \(error.localizedDescription)")
             }
         }
+
+        // Persist the resolved shareUserMemory flag on the saved env and
+        // install user-memory hooks when enabled.
+        var saved = try store.load(named: name)
+        saved.shareUserMemory = shareUserMemoryDefault
+        try store.save(saved)
+        if shareUserMemoryDefault {
+            try? store.ensureUserMemoryHooks(for: name)
+        }
     }
 
     // MARK: - Wizard
 
     /// Loop through all tools, asking setup/skip and running the per-tool wizard for each "setup".
-    /// Returns configs and whether the user chose to install statusline (asked after Claude setup).
-    static func runWizard(store: EnvironmentStore) -> ([ToolSetupRunner.Config], installStatusline: Bool) {
+    /// Returns configs, whether the user chose to install statusline (asked after Claude setup),
+    /// and whether to enable the cross-project user-memory layer.
+    static func runWizard(store: EnvironmentStore) -> ([ToolSetupRunner.Config], installStatusline: Bool, shareUserMemory: Bool) {
         var configs: [ToolSetupRunner.Config] = []
         var installStatusline = false
         for tool in Tool.allCases {
@@ -121,7 +144,8 @@ public struct CreateCommand: ParsableCommand {
                 installStatusline = askInstallStatusline()
             }
         }
-        return (configs, installStatusline)
+        let shareUserMemory = askShareUserMemory()
+        return (configs, installStatusline, shareUserMemory)
     }
 
     static func askInstallStatusline() -> Bool {
@@ -133,6 +157,15 @@ public struct CreateCommand: ParsableCommand {
         return selector.run() == 0
     }
 
+    static func askShareUserMemory() -> Bool {
+        let selector = SingleSelect(
+            title: L10n.Create.askShareUserMemory,
+            options: [L10n.Create.shareUserMemoryYes, L10n.Create.shareUserMemoryNo],
+            selected: 0
+        )
+        return selector.run() == 0
+    }
+
     static func askSetupTool(_ toolName: String, defaultYes: Bool) -> Bool {
         let selector = SingleSelect(
             title: L10n.Create.askSetupTool(toolName),
@@ -150,13 +183,15 @@ public struct CreateCommand: ParsableCommand {
         tool: Tool,
         isolateSessions: Bool = false,
         isolateMemory: Bool = false,
+        shareUserMemory: Bool = true,
         store: EnvironmentStore
     ) throws {
         let env = OrreryEnvironment(
             name: name,
             description: description,
             isolatedSessionTools: isolateSessions ? [tool] : [],
-            isolateMemory: isolateMemory
+            isolateMemory: isolateMemory,
+            shareUserMemory: shareUserMemory
         )
         try store.save(env)
         try store.addTool(tool, to: name)
@@ -167,5 +202,9 @@ public struct CreateCommand: ParsableCommand {
             let claudeConfigDir = store.toolConfigDir(tool: .claude, environment: name)
             store.linkOrreryMemory(projectKey: projectKey, envName: name, claudeConfigDir: claudeConfigDir)
         }
+
+        if shareUserMemory {
+            try store.ensureUserMemoryHooks(for: name)
+        }
     }
 }