lkjagent

lkjagent is a docs-driven, memory-centric personal librarian agent. The repository treats docs/ as the only source of truth and regenerates code/, data/, and the root automation layer from markdown blueprints.

What is in scope

• a single-user, long-running process with background worker agents
• a browser dashboard with Console, Feed, Tasks, Agents, RAM, and Config pages
• chunked large-input processing with parallel workers and proactive progress/completion updates
• RAM/STORAGE-based agent state with parent, intake, curator, and worker-pool roles
• /status, /ram, /search, /export, /config, /models, /feed, /agents, /tasks, /task, and /help
• a docs-first rebuild and verify workflow

Quickstart

1. Copy .env.example to .env if you want local Docker Compose defaults.
2. Run make rebuild to materialize artifacts from docs/.
3. Run make verify and make test.
4. Start the process with make run.
5. Open the printed browser URL, or use the local terminal session for commands.
6. Normal messages queue into background jobs. Very large inputs are split into parallel chunks, and progress lands in the dashboard feed without waiting for another user turn.
7. The default runtime starts 16 worker slots and 16 autonomous background agents. They share a global 16-request model budget, and low-priority autonomy leaves room for foreground user work.

Docker Compose modes

• External LM Studio: set LOCAL_LLM_ENDPOINT to http://host.docker.internal:1234/v1 or your LAN IP, then run docker compose up --build.
• Bundled vLLM service: keep LOCAL_LLM_ENDPOINT=http://local-llm:8000/v1, then run docker compose --profile bundled-llm up --build.
• The app publishes ${WEB_SERVER_PORT:-8080} so a browser can connect to the hosted dashboard.
• LOCAL_LLM_TIMEOUT_SECS now defaults to 0, which disables socket timeouts.
• The default autonomy loop runs every 8 seconds across 16 background agents.
• Workers and autonomy share the same global_parallelism request budget, and autonomy uses low-priority slots so user tasks are not starved.
• Edit data/config/request-template.json when you want to control the full OpenAI-compatible JSON request body.

Repository layout

• docs/: canonical source of truth, schemas, prompts, and rebuild instructions
• code/: Rust workspace containing lkjagent and repoctl
• data/: mounted runtime state root (ram/, storage/, config/, cache/, logs/, exports/)

Key commands

• /status: process state, active agents, recent autonomous activity, queue summary
• /ram [agent]: RAM body plus provenance
• /search QUERY: RAM first, STORAGE second
• /export [profile]: export default, full-snapshot, or transcript-pack
• /config: effective runtime paths, chunking, endpoint, timeout, worker count, and web settings
• /models: list models advertised by the configured OpenAI-compatible endpoint
• /feed: inspect the asynchronous user/agent/progress feed
• /agents: inspect agent state and RAM/activity previews
• /tasks: list recent queued, running, synthesizing, failed, and completed tasks
• /task ID: inspect one task in detail
• /help: command sheet

Rebuild contract

Blueprint files live under docs/blueprints/generated/files/. repoctl rebuild --root . rewrites every non-doc artifact declared there. repoctl verify --root . checks README coverage, rebuild drift, and the 300-line rule.

See docs/README.md for the full map.