glm-5.1
8c025c3433
- Copy core source from alkhub_ts/packages/core/pubsub/ with import path fixups (typed_event_target.ts → types.ts, .ts → .js extensions) - Make PubSubPublishArgsByKey exported (was private type, needed by barrel) - Add package.json with sub-path exports and optional peer deps (ioredis) - Add tsup.config.ts with multi-entry + splitting for tree-shaking - Add tsconfig.json, vitest.config.ts, .gitignore - Add AGENTS.md with project conventions and adapter checklist - Add architecture docs following taskgraph/alkhub pattern: docs/architecture/README.md, api-surface.md, event-targets.md, iroh-transport.md, build-distribution.md - Add ADRs: 001-graphql-yoga-fork, 002-tree-shake-pattern - Copy migration research doc to docs/research/migration.md - Dual-license MIT OR Apache-2.0 (matching taskgraph)
110 lines
5.8 KiB
Markdown
110 lines
5.8 KiB
Markdown
## Memory Tools (via @alkdev/open-memory plugin)
|
|
|
|
You have access to two tools for managing your context and accessing session history:
|
|
|
|
### memory({tool: "...", args: {...}})
|
|
|
|
Read-only tool for introspecting your session history and context state. Available operations:
|
|
- `memory({tool: "help"})` — full reference with examples
|
|
- `memory({tool: "summary"})` — quick counts of projects, sessions, messages, todos
|
|
- `memory({tool: "sessions"})` — list recent sessions (useful for finding past work)
|
|
- `memory({tool: "children", args: {sessionId: "ses_..."}})` — list sub-agent sessions spawned from a parent
|
|
- `memory({tool: "messages", args: {sessionId: "..."}})` — read a session's conversation
|
|
- `memory({tool: "messages", args: {sessionId: "...", role: "assistant"}})` — read only assistant messages
|
|
- `memory({tool: "messages", args: {sessionId: "...", showTools: true}})` — include tool-call output
|
|
- `memory({tool: "message", args: {messageId: "msg_..."}})` — read a single message by ID
|
|
- `memory({tool: "search", args: {query: "..."}})` — search across all conversations
|
|
- `memory({tool: "compactions", args: {sessionId: "..."}})` — view compaction checkpoints
|
|
- `memory({tool: "context"})` — check your current context window usage
|
|
|
|
### memory_compact()
|
|
|
|
Trigger compaction on the current session. This summarizes the conversation so far to free context space.
|
|
|
|
**When to use memory_compact:**
|
|
- When context is above 80% (check with `memory({tool: "context"})`)
|
|
- When you notice you're losing track of earlier conversation details
|
|
- At natural breakpoints in multi-step tasks (after completing a subtask, before starting a new one)
|
|
- When the system prompt shows a yellow/red/critical context warning
|
|
- Proactively, rather than waiting for automatic compaction at 92%
|
|
|
|
**When NOT to use memory_compact:**
|
|
- When context is below 50% (it wastes a compaction cycle)
|
|
- In the middle of a complex edit that you need immediate context for
|
|
- When the task is nearly complete (just finish the task instead)
|
|
|
|
Compaction preserves your most important context in a structured summary — you will continue the session with the summary as your starting point.
|
|
|
|
## Worktree Tool (via @alkimiadev/open-coordinator plugin)
|
|
|
|
You have access to the `worktree` tool for git worktree management and session coordination. Call with `{action, args}`:
|
|
|
|
### Coordinator Operations (available when session is not spawned by another session)
|
|
|
|
- `worktree({action: "list"})` — List git worktrees
|
|
- `worktree({action: "dashboard"})` — Worktree dashboard with session info
|
|
- `worktree({action: "spawn", args: {tasks: [...], prompt: "..."}})` — Spawn parallel worktrees + sessions
|
|
- `worktree({action: "sessions"})` — Query spawned session status
|
|
- `worktree({action: "message", args: {sessionID: "...", message: "..."}})` — Message a session
|
|
- `worktree({action: "abort", args: {sessionID: "..."}})` — Abort a session
|
|
- `worktree({action: "cleanup", args: {action: "remove", pathOrBranch: "..."}})` — Remove worktree
|
|
- `worktree({action: "help"})` — Show all available operations
|
|
|
|
### Implementation Operations (available when session is spawned by a coordinator)
|
|
|
|
- `worktree({action: "current"})` — Show your worktree mapping
|
|
- `worktree({action: "notify", args: {message: "...", level: "info|blocking"}})` — Report to coordinator
|
|
- `worktree({action: "status"})` — Show worktree git status
|
|
|
|
The plugin auto-injects `workdir` for bash commands when the session is mapped to a worktree.
|
|
|
|
## Project: @alkdev/pubsub
|
|
|
|
Type-safe publish/subscribe with pluggable event target adapters (in-process, Redis, WebSocket, Iroh). Core is adapted from graphql-yoga (MIT). Dual-licensed MIT / Apache-2.0.
|
|
|
|
### Commands
|
|
|
|
- `npm run build` — Build with tsup (ESM + CJS + declarations)
|
|
- `npm run lint` — Type-check with `tsc --noEmit`
|
|
- `npm test` — Run tests with vitest
|
|
- `npm run test:watch` — Watch mode
|
|
- `npm run test:coverage` — Coverage report (v8)
|
|
|
|
### Architecture
|
|
|
|
See `docs/architecture/` for full spec. Key points:
|
|
|
|
- **Barrel + sub-path exports**: `src/index.ts` re-exports core + operators. Each adapter has its own sub-path entry (`@alkdev/pubsub/event-target-redis`, etc.).
|
|
- **Peer dep isolation**: Redis and Iroh adapters are optional peer deps. Consumers only install the ones they need.
|
|
- **TypedEventTarget contract**: All adapters implement the same `addEventListener`/`dispatchEvent`/`removeEventListener` interface. `createPubSub` is transport-agnostic.
|
|
- **No comments in source**: Do not add comments to code unless explicitly asked.
|
|
- **License headers**: Files adapted from graphql-yoga must preserve their MIT attribution headers.
|
|
|
|
### Source Layout
|
|
|
|
```
|
|
src/
|
|
index.ts — Barrel: re-exports core API + operators
|
|
types.ts — TypedEvent, TypedEventTarget, etc. (adapted from graphql-yoga)
|
|
create_pubsub.ts — createPubSub factory (adapted from graphql-yoga)
|
|
operators.ts — filter, map, pipe (adapted from graphql-yoga)
|
|
event-target-redis.ts — createRedisEventTarget (peer dep: ioredis)
|
|
# Future adapters:
|
|
# event-target-websocket.ts — (peer dep: none, web standard)
|
|
# event-target-iroh.ts — (peer dep: @rayhanadev/iroh)
|
|
```
|
|
|
|
### Dependencies
|
|
|
|
Runtime: `@repeaterjs/repeater` (direct, ~3KB).
|
|
Peer (optional): `ioredis@^5.0.0` (Redis adapter), `@rayhanadev/iroh` (Iroh adapter, future).
|
|
Dev: `tsup`, `typescript`, `vitest`, `@vitest/coverage-v8`, `ioredis` (for type resolution).
|
|
|
|
### Adding an Adapter Checklist
|
|
|
|
1. Create `src/event-target-{name}.ts` implementing `TypedEventTarget`
|
|
2. Add entry to `tsup.config.ts` entry array
|
|
3. Add sub-path export to `package.json` exports map
|
|
4. Add peer dep to `package.json` peerDependencies (with peerDependenciesMeta optional: true)
|
|
5. Add to `src/index.ts` barrel re-export
|
|
6. Write tests in `test/event-target-{name}.test.ts` |