Ledgenter vs markdown files and the prompt
Most agent setups start the same way: a markdown file for state and a long system prompt for the rules. It's the obvious first move, and for a one-off task it's the right one.
It comes apart in three predictable places. Two agents edit the same file and clobber each other. A new session re-reads the whole file — or starts blank — and re-pays the context tokens every turn. And 'done' is a line you hope got updated. Ledgenter keeps the same information in a shared database the agent queries on demand: durable across sessions, safe under concurrency, and cheaper than re-reading everything each turn.
A file is fine for one agent on one task. The moment work outlives a session or a second agent joins, you need claims, durable decisions, and a checked 'done' a file can't give you.
| Dimension | Ledgenter | Files + the prompt |
|---|---|---|
| State across sessions | Durable in a database, queried when needed | Re-read the whole file each run, or lose it |
| Two agents at once | Atomic claims, handoffs, shared decisions | Both edit one file and overwrite each other |
| Finding the right thing | Semantic and lexical search over knowledge | grep, or stuff it all into context |
| “Done” you can trust | A verification gate on a dependency graph | A line you hope was updated |
| Context cost | Query the slice you need; don't re-pay for state | Re-read everything every turn |
| Audit trail | Append-only decision and activity logs | Whatever the file happened to record |
A single agent on a throwaway task does not need a database — a file is faster to set up and fine to throw away. Ledgenter earns its place the moment the work outlives one context window, or a second agent joins.
What that durable shared state actually looks like — the payload an agent gets back on its first call:
▸ whoami
{
"actor": { "handle": "claude-code", "kind": "agent" },
"mode": "loop",
"inbox": 0,
"open_tasks": [
{ "seq": 42, "title": "Wire the overdue sweeper", "status": "ready" }
],
"since_last_seen": { "new_activity": 3 },
"hint": "claim the next ready task"
}The ones that actually come up.
My CLAUDE.md / system prompt already works. Why change?
Keep it — Ledgenter doesn't replace your prompt, it replaces the state your prompt has to carry. The rules and voice stay in the prompt; the projects, tasks, decisions, and findings move to a store the agent queries, so they survive a new session and don't bloat every turn's context.
Isn't a database slower than reading a local file?
For one tiny file, marginally. But a growing state file gets re-read in full every turn, which costs tokens and latency that scale with its size. Querying just the slice you need — the three open tasks, the one relevant decision — is cheaper as the work grows, and it's the only option once two agents share it.
How do agents talk to Ledgenter?
Through an MCP server. Point any MCP-capable host (Claude Code, Cursor, your own agent) at it, and the tools — task_claim, decision_log, knowledge_search, handoff_create — show up alongside the agent's other tools. Setup is about five minutes.