Development
Setup
git clone [email protected]:mrkhachaturov/hindclaw.git
cd hindclaw
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)
├── 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 + per-agent overrides. Shallow merge, agent entry 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 (managed via Terraform). 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