feat: context store, lazy recall, hooks, and self-documenting hints by santoshkumarradha · Pull Request #6 · Agent-Field/plandb

santoshkumarradha · 2026-03-26T04:10:23Z

Summary

Four agent-facing platform features that make PlanDB self-discoverable and knowledge-persistent. No templates, no examples, no docs — pure infrastructure that every downstream feature builds on.

1. Context Store with BM25 Search

Graph-native knowledge base. Agents record what they discover mid-task, and it persists across sessions.

plandb context "JWT expiry conflicts with session cache" --kind discovery
plandb search "rate limiting"        # BM25 across context + task descriptions
plandb contexts --kind decision      # list all decisions

--kind is freeform (not an enum) — agents define their own taxonomy
Auto-links to running task (no --task flag needed)
SQLite FTS5, zero external dependencies
Available on all 3 interfaces: CLI, MCP, HTTP

2. Lazy Recall

When plandb go claims a task, BM25 auto-searches context using the task's title+description and injects up to 3 relevant entries. Agents get knowledge without explicitly searching.

Zero prompt tokens needed to teach this — it just appears in the go response.

3. Task Lifecycle Hooks

--pre-hook and --post-hook shell commands on tasks. Fire at state transitions with env vars (PLANDB_TASK_ID, PLANDB_TASK_TITLE, etc.). Advisory — failures warn but never block. Included in template export/import.

4. Contextual Action Hints

Every CLI response teaches the agent what to do next. Kind-aware: research tasks hint "record discoveries", code tasks hint "split if complex". Also teaches compound graph features (recursive split, cross-level deps).

+ Prompt Sync

All 3 interface prompts (CLI, MCP, HTTP) and --help updated to cover these features. Includes bug fixes: --kind default corrected to "discovery", help text references fixed from --type to --kind, hints slimmed from 9 lines to 1-2.

Validation

7+ agent tests (Codex, Gemini) across these features
Agents average 3-5 context entries per session
Agents exercise features discovered only via hints (search, split, context)
Lazy recall: agents act on recalled context without being told to search
All 8 tests pass, clean build

Files changed (14 source files, 1147 lines)

Area	Files	What
Context store	`db/learnings.rs`, `db/schema.rs`, `db/mod.rs`	FTS5 tables, CRUD, BM25 search
Lazy recall	`cli/task/helpers.rs`, `cli/task/commands.rs`	BM25 term extraction, auto-inject on `go`
Hooks	`db/tasks.rs`, `db/templates.rs`, `models/task.rs`, `db/tests.rs`	Schema + execution + export
Hints	`cli/task/commands.rs`, `cli/mod.rs`	Kind-aware hints, compound graph hints
MCP	`mcp/tools.rs`	3 new tools: context_create, search, context_list
HTTP	`server/routes.rs`	3 new endpoints: POST /context, GET /contexts, GET /search
Prompts	`main.rs`	CLI, MCP, HTTP prompts synced

Test plan

cargo build — clean
cargo test — 8/8 pass
Context store: create, list, search, auto-link, freeform kinds
Lazy recall: BM25 matching on plandb go
Hooks: pre_hook/post_hook fire at transitions, advisory on failure
Hints: kind-aware output on go, slimmed output on done
MCP: 3 new tools functional
HTTP: 3 new endpoints functional
Prompts: CLI, MCP, HTTP all reference new features

New commands: plandb context "what you learned" --type discovery # attach context to project graph plandb search "query" # BM25-ranked search across everything plandb contexts [--kind decision] # list context entries plandb prune <id> # remove context entry Context entries are project-wide knowledge that persists across sessions, searchable via SQLite FTS5 (BM25 ranking). Unlike task notes (scoped to one task), context is queryable across the entire project graph. Types: discovery, decision, pattern, blocker, reference Optional: --task (link to task), --tags (comma-separated) Search returns ranked results from both context entries AND task descriptions, giving agents a unified knowledge base across the project graph. Zero dependencies — FTS5 is built into SQLite (bundled with rusqlite).

Previously context entries were limited to 5 hardcoded types: discovery, decision, pattern, blocker, reference. Now --type is a freeform string — agents define their own types based on their domain: constraint, observation, bug, milestone, hypothesis, metric, api-change, etc. This makes the context store domain-agnostic and extensible without code changes. IDs now use c- prefix (ctx-). Also fixed search output display (showed [?] instead of [ctx]).

Changes based on AI agent + product designer critique: 1. --type renamed to --kind (consistency with PlanDB conventions) 2. Auto-link to current running task when adding context (agents no longer need to pass --task explicitly) 3. Fixed search output source tag ("context" → [ctx]) 4. IDs now use c- prefix for context entries The auto-link feature is the key ergonomic improvement: agents adding context mid-task get automatic task association without tracking IDs. This mirrors how humans naturally annotate work.

When an agent claims a task with `plandb go`, the response now automatically includes relevant context entries from the project's knowledge base. BM25 search extracts key terms from the task title and description, returning up to 3 matching context entries. This eliminates the need for agents to explicitly search before starting work — discoveries, decisions, and constraints are surfaced proactively. Applied to all three interfaces: CLI, MCP, and HTTP.

Shell commands that execute at task state transitions: - pre_hook fires when task transitions to running (plandb go) - post_hook fires when task transitions to done (plandb done) Environment variables set for hooks: PLANDB_TASK_ID, PLANDB_PROJECT_ID, PLANDB_TASK_TITLE, PLANDB_AGENT_ID Hooks are advisory — failures print warnings but never block operations. Included in export/import templates for replayable procedures. Usage: plandb add "Run linter" --pre-hook 'echo "starting $PLANDB_TASK_TITLE"' \ --post-hook 'echo "done: $PLANDB_TASK_ID"'

Every CLI response now teaches the agent what it can do next: - init: shows dependency syntax and core loop - go: shows context, split, search, and done commands - done: shows reassess, next task, insert, and parallel options The primary user of PlanDB is the agent, not the human. CLI output is self-documenting — agents auto-discover features.

…scovery The prompt now covers all new features: - Lazy recall: plandb go auto-surfaces relevant context - Hooks: --pre-hook/--post-hook for task automation - Context store: discovery/decision/pattern with BM25 search - Templates: export/import with context entries - Self-documenting: "every command shows hints — read them" Prompt stays compact at 120 lines (was 110 before new features).

MCP prompt now includes context store, lazy recall, hooks, and templates so Claude Code / Cursor / Windsurf users get the same feature awareness.

Hints shown after claiming a task are now tailored to the task kind: - research: record discoveries and decisions - code: record design choices, split if complex - test: record test gaps/bugs, check known issues - review: record findings, annotate tasks with feedback - generic: general-purpose hints Also adds task kind to go response JSON for downstream use.

Prompt now teaches agents about recursive decomposition and cross-level dependencies — the most powerful and unique PlanDB features. Agents learn they can: split to any depth, zoom with use/use.., and create dependencies between tasks at different hierarchy levels.

Three new HTTP endpoints: POST /context — create context entry (auto-links to running task) GET /contexts?project_id=X&kind=Y — list context entries GET /search?project_id=X&q=query — BM25 search across context + tasks All three interfaces now have full context/search support: CLI, MCP (pending), and HTTP.

Three new MCP tools for Claude Code / Cursor / Windsurf users: plandb_context_create — add context entry (auto-links to running task) plandb_search — BM25 search across context + tasks plandb_context_list — list context entries with optional kind filter All three interfaces now have complete context/search support: CLI: plandb context / plandb search / plandb contexts MCP: plandb_context_create / plandb_search / plandb_context_list HTTP: POST /context / GET /search / GET /contexts

The help output now covers all features: - Context store & search (BM25, lazy recall, auto-link) - Templates as learning framework (browse, import, export, compound) - Resume for session continuity Agents reading --help get the complete picture.

Fixes: - P0: Context --kind default changed from "note" to "discovery" (consistent) - P0: Fixed --type references in help text → --kind (correct flag name) - Slimmed go_cmd hints from 9 lines to 2 (token efficient) - Slimmed done_cmd hints from 8 lines to 1-2 Removed: - 4 redundant security audit templates (kept simple + comprehensive) - 6 redundant examples (kept 5 that each show unique capability) Templates: 12 → 8 (each adds unique value) Examples: 11 → 5 (no redundancy)

CLAassistant · 2026-03-26T04:10:36Z

All committers have signed the CLA.

Review findings: - README copy-paste prompt was missing context/search/hooks — agents copying it got no awareness of the most valuable new features - README CLI Reference had no context store or hooks section - examples/PLANDB_PROMPT.md had no context/search commands - --help referenced plandb resume and plandb templates (nonexistent in this branch) Fixes: - README copy-paste: added context, search, lazy recall mention - README CLI Reference: added Context Store & Search + Hooks sections - PLANDB_PROMPT.md: added context/search commands + lazy recall note - --help: removed resume/templates references, kept import/export

santoshkumarradha · 2026-03-26T04:16:56Z

Code Review

What's in this PR (features 1-4 + prompt sync)

Feature	Source files	Prompts coverage
Context Store + BM25	`db/learnings.rs`, `db/schema.rs`, `cli/mod.rs`	CLI, MCP, HTTP, --help, README, PLANDB_PROMPT
Lazy Recall	`cli/task/helpers.rs`, `cli/task/commands.rs`, `mcp/tools.rs`, `server/routes.rs`	CLI, MCP, HTTP, --help, README
Lifecycle Hooks	`db/tasks.rs`, `db/templates.rs`, `models/task.rs`, `cli/task/commands.rs`	CLI, MCP, --help, README
Contextual Hints	`cli/task/commands.rs`, `cli/mod.rs`	N/A (self-documenting CLI output)
Prompt Sync	`main.rs`, `cli/mod.rs`, `README.md`, `examples/PLANDB_PROMPT.md`	All interfaces

What's NOT in this PR (confirmed absent)

plandb resume — not referenced, command doesn't exist
plandb templates (browse) — not referenced, command doesn't exist
done --context — not included
Template YAML files — not included
Example directories — not included
Documentation/findings files — not included

Review findings (all fixed)

README copy-paste prompt was missing context/search/hooks → added
README CLI Reference had no context store or hooks section → added
examples/PLANDB_PROMPT.md had no context/search → added with lazy recall note
--help referenced plandb resume and plandb templates (nonexistent) → removed
--help templates section now only references import/export (exist on main)

Code quality

execute_hook() is correctly advisory (warn on failure, never block)
Hook env vars set correctly (PLANDB_TASK_ID, PLANDB_PROJECT_ID, PLANDB_TASK_TITLE, PLANDB_AGENT_ID)
BM25 search uses SQLite FTS5 (zero deps, bundled with rusqlite)
Context --kind default correctly set to "discovery" (bug fixed in cleanup commit)
Hints slimmed from 9 lines to 1-line (token efficient)
All 3 interfaces (CLI, MCP, HTTP) have identical context/search capabilities

8/8 tests pass, clean build. Ship it.

Templates (browse, learning framework) are a separate feature not in this PR. export/import commands exist but the template workflow shouldn't be taught to agents in prompts for features that don't include it. Removed from: - CLI prompt: Templates (Replayable Procedures) section - MCP prompt: templates line in Key Concepts - --help: TEMPLATES section - done_cmd: "plandb export > template.yaml" completion hint export/import commands still exist and work — just not advertised in prompts until the template feature PR lands.

santoshkumarradha added 15 commits March 26, 2026 09:37

feat: update MCP prompt with context store, lazy recall, and hooks

b87bc79

MCP prompt now includes context store, lazy recall, hooks, and templates so Claude Code / Cursor / Windsurf users get the same feature awareness.

feat: update HTTP prompt with context store and search endpoints

8467c0e

santoshkumarradha merged commit 3fb64c1 into main Mar 26, 2026
1 of 2 checks passed

santoshkumarradha deleted the feat/core-platform-features branch March 26, 2026 04:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: context store, lazy recall, hooks, and self-documenting hints#6

feat: context store, lazy recall, hooks, and self-documenting hints#6
santoshkumarradha merged 17 commits intomainfrom
feat/core-platform-features

santoshkumarradha commented Mar 26, 2026

Uh oh!

CLAassistant commented Mar 26, 2026 •

edited

Loading

Uh oh!

santoshkumarradha commented Mar 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

santoshkumarradha commented Mar 26, 2026

Summary

1. Context Store with BM25 Search

2. Lazy Recall

3. Task Lifecycle Hooks

4. Contextual Action Hints

+ Prompt Sync

Validation

Files changed (14 source files, 1147 lines)

Test plan

Uh oh!

CLAassistant commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

santoshkumarradha commented Mar 26, 2026

Code Review

What's in this PR (features 1-4 + prompt sync)

What's NOT in this PR (confirmed absent)

Review findings (all fixed)

Code quality

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

CLAassistant commented Mar 26, 2026 •

edited

Loading