https://github.com/karmaniverous/jeeves-meta
Knowledge synthesis engine for the Jeeves platform. Discovers .meta/ directories, gathers context from files and vector search, and produces structured synthesis artifacts via a three-step LLM pipeline (architect, builder, critic).
https://github.com/karmaniverous/jeeves-meta
ai-agent fastify jeeves knowledge-synthesis llm metadata openclaw qdrant typescript vector-search
Last synced: 2 months ago
JSON representation
Knowledge synthesis engine for the Jeeves platform. Discovers .meta/ directories, gathers context from files and vector search, and produces structured synthesis artifacts via a three-step LLM pipeline (architect, builder, critic).
- Host: GitHub
- URL: https://github.com/karmaniverous/jeeves-meta
- Owner: karmaniverous
- License: bsd-3-clause
- Created: 2026-03-08T06:49:56.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T01:41:48.000Z (2 months ago)
- Last Synced: 2026-04-03T01:42:43.033Z (2 months ago)
- Topics: ai-agent, fastify, jeeves, knowledge-synthesis, llm, metadata, openclaw, qdrant, typescript, vector-search
- Language: TypeScript
- Homepage: https://docs.karmanivero.us/jeeves-meta/
- Size: 1.37 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# jeeves-meta
Knowledge synthesis engine for the Jeeves platform. Transforms raw data archives into concise, queryable meta-analyses through a three-step LLM pipeline: **Architect** → **Builder** → **Critic**.
## Overview
jeeves-meta is an HTTP service that discovers `.meta/` directories via the jeeves-watcher filesystem walk endpoint (`POST /walk`), builds an ownership tree, and schedules synthesis cycles based on weighted staleness. Each cycle:
1. **Architect** — analyzes data shape and crafts a task brief with search strategies
2. **Builder** — executes the brief, queries the semantic index, and produces a synthesis
3. **Critic** — spot-checks claims, evaluates against steering prompts, and provides feedback
Results are written to `.meta/meta.json` files with full archive history, enabling self-improving feedback loops.
Metas can declare explicit cross-references (`_crossRefs`) to other metas, forming a heterarchical mesh that enables organizational views across source domains.
## Packages
| Package | Description |
|---------|-------------|
| [`@karmaniverous/jeeves-meta`](packages/service/README.md) | HTTP service — Fastify API, built-in scheduler, synthesis queue, CLI |
| [`@karmaniverous/jeeves-meta-openclaw`](packages/openclaw/README.md) | OpenClaw plugin — thin HTTP client, interactive tools, TOOLS.md injection |
## Architecture
- **jeeves-meta service** runs as a standalone HTTP service (NSSM/systemd/launchd)
- **Built-in scheduler** (croner-based) discovers stale candidates and enqueues them
- **GatewayExecutor** spawns LLM sessions via the OpenClaw gateway `/tools/invoke` endpoint
- **jeeves-watcher** provides filesystem enumeration (`POST /walk`) and hosts virtual inference rules
- **OpenClaw plugin** is a thin HTTP client — all logic lives in the service
## Synthesis Data Flow
## Quick Start
### Install and start the service
```bash
npm install -g @karmaniverous/jeeves-meta
# Print NSSM/systemd/launchd install instructions
jeeves-meta service install --config /path/to/jeeves-meta.config.json
# Or start directly
jeeves-meta start --config /path/to/jeeves-meta.config.json
```
### CLI commands
```bash
jeeves-meta status # service health + queue state
jeeves-meta list # list all metas with summary
jeeves-meta detail # full detail for a single meta
jeeves-meta preview # dry-run next synthesis
jeeves-meta synthesize # enqueue synthesis
jeeves-meta seed # create .meta/ for a new path
jeeves-meta unlock # remove stale .lock file
jeeves-meta config # query active config (supports JSONPath)
jeeves-meta service start|stop|status|install|remove
```
### As an OpenClaw plugin
Install the plugin package. Eight tools become available to the agent:
- `meta_list` — list metas with summary stats and filtering
- `meta_detail` — full detail for a single meta with optional archive history
- `meta_trigger` — manually trigger synthesis (enqueues work)
- `meta_preview` — dry-run showing what inputs would be gathered
- `meta_seed` — create `.meta/` directory for a new path (with optional cross-refs and steer)
- `meta_unlock` — remove stale `.lock` from a meta entity
- `meta_config` — query service configuration with optional JSONPath
- `meta_queue` — queue management: list pending, clear queue, abort current synthesis
## Configuration
Minimal config (built-in prompts, default schedule):
```json
{
"watcherUrl": "http://localhost:1936",
"gatewayUrl": "http://127.0.0.1:18789",
"gatewayApiKey": "your-api-key"
}
```
Full example with all optional fields:
```json
{
"watcherUrl": "http://localhost:1936",
"gatewayUrl": "http://127.0.0.1:18789",
"gatewayApiKey": "your-api-key",
"defaultArchitect": "@file:prompts/architect.md",
"defaultCritic": "@file:prompts/critic.md",
"port": 1938,
"schedule": "*/30 * * * *",
"reportChannel": "C0AK9D0GL5A",
"metaProperty": { "_meta": "current" },
"metaArchiveProperty": { "_meta": "archive" },
"logging": { "level": "info" }
}
```
See the [Configuration Guide](packages/service/guides/configuration.md) for all fields and defaults.
## Development
```bash
npm install
npm run build # build both packages
npm run lint # lint both packages
npm run typecheck # typecheck both packages
npm test # run all tests
npm run knip # detect unused exports/deps
npm run docs # generate TypeDoc documentation
```
## Documentation
- **[Service Guides](packages/service/guides/index.md)** — concepts, configuration, orchestration, scheduling, architecture
- **[CLI Reference](packages/service/guides/cli.md)** — all CLI commands with usage
- **[Plugin Guides](packages/openclaw/guides/index.md)** — setup, tools reference, virtual rules, TOOLS.md injection
## License
BSD-3-Clause
---
Built for you with ❤️ on Bali by [Jason Williscroft](https://github.com/karmaniverous) & [Jeeves](https://github.com/jgs-jeeves).