@pi-unipi/unipi 0.1.1

package/packages/memory/index.ts

@@ -0,0 +1,209 @@
+/**
+ * @unipi/memory — Extension entry
+ *
+ * Persistent cross-session memory with vector search.
+ * All storage is project-scoped. "Global" tools search across all projects.
+ * Injects memory titles at session start.
+ * Auto-consolidates on compaction.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import {
+  UNIPI_EVENTS,
+  MODULES,
+  emitEvent,
+  getPackageVersion,
+} from "@pi-unipi/core";
+
+// Get info registry from global (avoids direct import issues with pi's extension loading)
+function getInfoRegistry() {
+  const g = globalThis as any;
+  return g.__unipi_info_registry;
+}
+import {
+  MemoryStorage,
+  getProjectName,
+  searchAllProjects,
+  listAllProjects,
+} from "./storage.js";
+import { registerMemoryTools, MEMORY_TOOLS } from "./tools.js";
+import { registerMemoryCommands } from "./commands.js";
+
+/** Package version */
+const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
+
+/** Storage instance for current project */
+let projectStorage: MemoryStorage | null = null;
+
+/**
+ * Get storage for the current project.
+ */
+function getStorage(): MemoryStorage {
+  if (!projectStorage) {
+    // Fallback: create new instance (shouldn't happen after session_start)
+    return new MemoryStorage("unknown");
+  }
+  return projectStorage;
+}
+
+export default function (pi: ExtensionAPI) {
+  // Register skills directory
+  const skillsDir = new URL("./skills", import.meta.url).pathname;
+  pi.on("resources_discover", async (_event, _ctx) => {
+    return {
+      skillPaths: [skillsDir],
+    };
+  });
+
+  // Register tools and commands
+  registerMemoryTools(pi, getStorage);
+  registerMemoryCommands(pi, getStorage);
+
+  // Session lifecycle
+  pi.on("session_start", async (_event, ctx) => {
+    // Initialize project storage
+    const projectName = getProjectName(ctx.cwd);
+    projectStorage = new MemoryStorage(projectName);
+    projectStorage.init();
+
+
+    // Announce module
+    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
+      name: MODULES.MEMORY,
+      version: VERSION,
+      commands: [
+        "unipi:memory-process",
+        "unipi:memory-search",
+        "unipi:memory-consolidate",
+        "unipi:memory-forget",
+        "unipi:global-memory-search",
+        "unipi:global-memory-list",
+      ],
+      tools: [
+        MEMORY_TOOLS.STORE,
+        MEMORY_TOOLS.SEARCH,
+        MEMORY_TOOLS.DELETE,
+        MEMORY_TOOLS.LIST,
+        MEMORY_TOOLS.GLOBAL_SEARCH,
+        MEMORY_TOOLS.GLOBAL_LIST,
+      ],
+    });
+
+    // Register info group
+    const registry = getInfoRegistry();
+    if (registry) {
+      console.debug("[memory] Registering info group");
+      registry.registerGroup({
+        id: "memory",
+        name: "Memory",
+        icon: "🧠",
+        priority: 60,
+        config: {
+          showByDefault: true,
+          stats: [
+            { id: "projectCount", label: "Project Memories", show: true },
+            { id: "totalCount", label: "Total Memories", show: true },
+            { id: "projects", label: "Projects", show: true },
+            { id: "recent", label: "Recent Memories", show: true },
+          ],
+        },
+        dataProvider: async () => {
+          if (!projectStorage) {
+            return {
+              projectCount: { value: "0" },
+              totalCount: { value: "0" },
+              projects: { value: "none" },
+              recent: { value: "none" },
+            };
+          }
+
+          const projectMemories = projectStorage.listAll();
+          const allMemories = listAllProjects();
+          const uniqueProjects = [...new Set(allMemories.map((m) => m.project))];
+
+          // Get 3 most recent memories (sorted by updated DESC in listAll)
+          const recentMemories = projectMemories.slice(0, 3);
+          const recentList = recentMemories.map(m => m.title).join("\n");
+
+          return {
+            projectCount: { value: String(projectMemories.length) },
+            totalCount: { value: String(allMemories.length) },
+            projects: {
+              value: uniqueProjects.length.toString(),
+              detail: uniqueProjects.slice(0, 5).join(", ") + (uniqueProjects.length > 5 ? ` +${uniqueProjects.length - 5} more` : ""),
+            },
+            recent: {
+              value: recentMemories.length > 0 ? recentMemories[0].title : "none",
+              detail: recentMemories.length > 1 ? recentMemories.slice(1).map(m => m.title).join("\n") : undefined,
+            },
+          };
+        },
+      });
+    }
+
+    // Show memory status in UI
+    if (ctx.hasUI) {
+      const projectCount = projectStorage.listAll().length;
+      const allMemories = listAllProjects();
+      const projectCountAll = allMemories.length;
+      ctx.ui.setStatus(
+        "unipi-memory",
+        `🧠 memory ${projectCount}p/${projectCountAll}all`
+      );
+    }
+  });
+
+  // Inject memory titles at session start
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (!projectStorage) return;
+
+    const projectName = getProjectName(ctx.cwd);
+    const projectMemories = projectStorage.listAll();
+
+    if (projectMemories.length === 0) {
+      return; // No memories to inject
+    }
+
+    let injection = "\n\n<memory>\n";
+    injection += `Available memories for project "${projectName}":\n\n`;
+
+    // Project memories
+    for (const m of projectMemories) {
+      injection += `- ${m.title}\n`;
+    }
+
+    injection += "\nUse memory_search to retrieve full content. Use memory_store to save new memories.\n";
+    injection += "Use global_memory_search to search across ALL projects.\n";
+    injection += "</memory>";
+
+    return {
+      systemPrompt: event.systemPrompt + injection,
+    };
+  });
+
+  // Auto-consolidation on compaction
+  pi.on("session_before_compact", async (event, ctx) => {
+    const { preparation } = event;
+
+    // Extract summary text
+    const summary = preparation.previousSummary || "";
+
+    if (!summary || summary.length < 100) {
+      // Summary too short to extract memories from
+      return;
+    }
+
+    // For now, just log that consolidation would happen
+    // Future: Use LLM to extract memories
+    console.log("[unipi/memory] Auto-consolidation triggered, summary length:", summary.length);
+
+    // Don't modify the compaction summary - return unchanged
+    return {};
+  });
+
+  // Cleanup on shutdown
+  pi.on("session_shutdown", async () => {
+    projectStorage?.close();
+    projectStorage = null;
+  });
+}

package/packages/memory/skills/memory/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: memory
+description: >
+  Persistent cross-session memory management. Store and retrieve user preferences,
+  project decisions, code patterns, and conversation summaries across sessions.
+  Use when you need to remember something important or recall past context.
+allowed-tools:
+  - memory_store
+  - memory_search
+  - memory_delete
+  - memory_list
+  - global_memory_store
+  - global_memory_search
+  - global_memory_list
+  - read
+---
+
+# Memory
+
+Persistent cross-session memory for Pi coding agent. Memories survive session restarts, compaction, and context resets.
+
+## When to Store Memory
+
+Store memory when you encounter:
+
+| Type | Examples | Title Format |
+|------|----------|--------------|
+| **Preference** | User likes tabs, prefers functional style | `style_typescript_prefer_tabs` |
+| **Decision** | Chose PostgreSQL over MySQL, JWT over sessions | `db_postgres_chosen_over_mysql` |
+| **Pattern** | How auth is structured, API naming conventions | `api_rest_versioning_v2` |
+| **Summary** | Key findings from debugging, research results | `perf_slow_query_root_cause` |
+
+## Naming Convention
+
+**Format:** `<most_important>_<less_important>_<lesser>`
+
+**Rules:**
+- Use underscores, not hyphens
+- Start with category (style, db, auth, api, arch, etc.)
+- Be specific: `auth_jwt_prefer_refresh_tokens` not `auth_tokens`
+- Keep under 60 characters
+
+**Good titles:**
+- `style_typescript_strict_mode_always`
+- `db_postgres_use_connection_pooling`
+- `arch_api_versioning_v2_breaking`
+- `perf_cache_redis_for_sessions`
+
+**Bad titles:**
+- `auth` (too vague)
+- `User prefers tabs` (not snake_case)
+- `auth-jwt-refresh` (hyphens, not underscores)
+
+## When to Search Memory
+
+Search memory when:
+
+1. **User references past work:** "Remember when we fixed the auth bug?"
+2. **Making similar decisions:** "What did we decide about database choice?"
+3. **Setting up new features:** "What's the user's coding style?"
+4. **Debugging recurring issues:** "Have we seen this error before?"
+
+## How to Use Tools
+
+### Store a memory:
+```
+memory_store(
+  title: "auth_jwt_prefer_refresh_tokens",
+  content: "User prefers short-lived access tokens (15min) with long-lived refresh tokens (30d). Always implement token rotation on refresh.",
+  tags: ["auth", "jwt", "preferences"],
+  type: "preference"
+)
+```
+
+### Search memories:
+```
+memory_search(query: "auth tokens")
+```
+
+### List all project memories:
+```
+memory_list()
+```
+
+### Delete a memory:
+```
+memory_delete(title: "auth_jwt_prefer_refresh_tokens")
+```
+
+## Project vs Cross-Project Search
+
+| Action | Scope | Tools |
+|--------|-------|-------|
+| **Store** | Always project-scoped | `memory_store` |
+| **Search this project** | Current project only | `memory_search` |
+| **Search all projects** | Cross-project | `global_memory_search` |
+| **List all** | Cross-project | `global_memory_list` |
+
+**All memories are project-scoped.** When you store a memory, it belongs to the current project. Use `global_memory_search` to search across ALL projects when looking for past work or user preferences.
+
+## Update-First Principle
+
+**Always check before creating.** Before storing a new memory:
+
+1. Search for similar memories
+2. If found and relevant → UPDATE the existing memory
+3. If not found → CREATE new memory
+
+This prevents memory duplication and keeps memory clean.
+
+## Consolidation
+
+When the user runs `/unipi:memory-consolidate` or during compaction:
+
+1. Review the session for memory-worthy items
+2. For each item:
+   - Search for existing similar memory
+   - Update if found, create if not
+3. Report what was stored/updated
+
+## Reading Memory Files
+
+Memory files are stored in `~/.unipi/memory/` as markdown with YAML frontmatter:
+
+```markdown
+---
+title: auth_jwt_prefer_refresh_tokens
+tags: [auth, jwt, preferences]
+project: my-app
+created: 2026-04-26T10:00:00Z
+updated: 2026-04-26T15:30:00Z
+type: preference
+---
+
+# Auth: Prefer Refresh Tokens
+
+User prefers short-lived access tokens (15min) with long-lived refresh tokens (30d).
+Always implement token rotation on refresh.
+```
+
+You can read these files directly with the `read` tool for full context.
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Store everything | Only store decisions, preferences, patterns, summaries |
+| Create duplicate memories | Search first, update existing |
+| Use vague titles | Use specific `<category>_<detail>` format |
+| Store in wrong scope | Project-specific = project scope, universal = global |
+| Forget to update | When context changes, update the memory |

package/packages/ralph/README.md

@@ -0,0 +1,101 @@
+# @pi-unipi/ralph
+
+Long-running iterative development loops for [Pi coding agent](https://github.com/badlogic/pi-mono).
+
+Start a loop, the agent works through iterations, reflects periodically, and completes when done. State persists across sessions.
+
+## Install
+
+```bash
+pi install npm:@pi-unipi/ralph
+```
+
+Or as part of the full suite:
+```bash
+pi install npm:unipi
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unipi:ralph start <name\|path>` | Start a new loop |
+| `/unipi:ralph stop` | Pause current loop |
+| `/unipi:ralph resume <name>` | Resume a paused loop |
+| `/unipi:ralph status` | Show all loops |
+| `/unipi:ralph cancel <name>` | Delete loop state |
+| `/unipi:ralph archive <name>` | Move loop to archive |
+| `/unipi:ralph clean [--all]` | Clean completed loops |
+| `/unipi:ralph list --archived` | Show archived loops |
+| `/unipi:ralph nuke [--yes]` | Delete all ralph data |
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--max-iterations N` | Stop after N iterations (default: 50) |
+| `--items-per-iteration N` | Suggest N items per turn (prompt hint) |
+| `--reflect-every N` | Reflect every N iterations |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `ralph_start` | Start a ralph loop (called by agent) |
+| `ralph_done` | Signal iteration complete (called by agent) |
+
+## How It Works
+
+1. **Start** — creates a task file in `.unipi/ralph/` and begins iteration loop
+2. **Iterate** — agent works on task, updates progress, calls `ralph_done`
+3. **Reflect** — optional reflection prompts at configurable intervals
+4. **Complete** — agent emits `COMPLETE` marker or max iterations reached
+5. **Persist** — state saved to disk, survives session restarts
+
+```
+start → iterate → done → iterate → ... → complete
+  ↑                                        │
+  └──── resume ────────────────────────────┘
+```
+
+## Task File Format
+
+Loops operate on markdown task files:
+
+```markdown
+# Task
+
+Redesign the authentication system.
+
+## Goals
+- Migrate to JWT refresh tokens
+- Add role-based access control
+
+## Checklist
+- [x] Design token rotation
+- [ ] Implement refresh endpoint
+- [ ] Add RBAC middleware
+- [ ] Write tests
+
+## Notes
+Session 1: Completed token rotation design.
+```
+
+## State Storage
+
+```
+.unipi/ralph/
+├── loop-name.state.json    ← active/paused state
+├── loop-name.md            ← task file
+└── archive/
+    └── loop-name.*         ← archived loops
+```
+
+## Integration
+
+- **@pi-unipi/core** — event types, constants, utilities
+- **@pi-unipi/info-screen** — registers info group showing loop status
+
+## License
+
+MIT