Development
Setup
git clone [email protected]:mrkhachaturov/hindsight-openclaw-pro.git
cd hindsight-openclaw-pro
npm install
npm run build # TypeScript -> dist/
npm test # unit tests
Source Structure
src/
├── index.ts # Plugin entry: init + hook registration
├── client.ts # Stateless Hindsight HTTP client (bankId per-call)
├── types.ts # Full type system
├── config.ts # Config resolver + bank file parser + $include
├── utils.ts # Shared utilities
├── hooks/
│ ├── recall.ts # before_prompt_build (single + multi-bank + reflect)
│ ├── retain.ts # agent_end (tags, context, observation_scopes)
│ └── session-start.ts # session_start (mental models)
├── sync/
│ ├── plan.ts # Diff engine: file vs server state
│ ├── apply.ts # Execute changeset against Hindsight API
│ ├── import.ts # Pull server state into local file
│ └── bootstrap.ts # First-run apply if bank is empty
├── permissions/
│ ├── types.ts # User, Group, Permission types + validation
│ ├── discovery.ts # Config directory scanner + index builder
│ ├── resolver.ts # 4-step permission resolution algorithm
│ ├── merge.ts # Group merge rules
│ └── index.ts # Barrel export
├── cli/
│ ├── index.ts # hindclaw CLI entry point
│ └── init.ts # hindclaw init command
├── embed-manager.ts # Local daemon lifecycle
├── derive-bank-id.ts # Bank ID derivation
└── format.ts # Memory formatting
Key Patterns
Two-level config. Plugin defaults in openclaw.json + bank config file overrides. Shallow merge, bank file wins.
Stateless client. Every client method takes bankId as first parameter. No instance-level bank state. Enables multi-bank operations.
Server-side vs behavioral. snake_case fields = server-side (synced to Hindsight via CLI). camelCase fields = behavioral (used by hooks at runtime).
Graceful degradation. All hooks catch errors and log warnings. Never crash the gateway.
Testing
npm test # unit tests (vitest)
npm run test:integration # needs running Hindsight API
Integration test environment:
| Variable | Default | Description |
|---|---|---|
HINDSIGHT_API_URL | http://localhost:8888 | Hindsight server URL |
HINDSIGHT_API_TOKEN | -- | Auth token (optional) |
Publishing
Push a v* tag -- GitHub Actions publishes to npm via OIDC trusted publisher.
Before tagging:
- Bump version in
package.json - Add changelog entry in
CHANGELOG.mdwith the exact same version (workflow reads it by tag) - Commit both files
- Tag and push
git tag v0.2.0
git push origin main --tags