djobs

Local project memory for AI coding agents.
Continue the repository instead of explaining it again in every new session.

See it work in 60 seconds

Install the VS Code extension, or install the CLI once:

pipx install djobs
# or: uv tool install djobs

djobs setup          # defaults to Copilot; add codex/claude/gemini/kimi/all as needed
djobs doctor
djobs memory list

A healthy first run does not require a project-local .vscode/mcp.json. djobs setup explicitly configures user-level host adapters. The VS Code extension can register MCP natively and, on the first MCP call, may create ~/.djobs/global.db and configure the detected Copilot adapter. Those are local user-level changes rather than a read-only probe; use djobs doctor to inspect them and djobs remove copilot to remove the managed adapter.

After an agent session records work, djobs memory list shows what can be recovered:

{
  "ok": true,
  "workspace": "oauth-service",
  "count": 3,
  "memories": [
    {
      "id": "6f3c...",
      "event": "user_intent",
      "summary": "Fix the OAuth callback loop without changing the public API.",
      "status": "active"
    },
    {
      "id": "ab91...",
      "event": "tool_failure",
      "summary": "Normalization removed '+' from the state parameter.",
      "status": "active"
    },
    {
      "id": "d204...",
      "event": "session_capsule",
      "summary": "Parser updated; one integration test remains.",
      "status": "active"
    }
  ]
}

The next session can call:

sync_workspace(query="Continue the OAuth callback fix")

and receive a compact continuation capsule containing the goal, constraints, progress, failures, next step, and current Git state. Stored text is returned as untrusted data; the current user request always remains authoritative.

The normal CLI

djobs --help is intentionally focused on the memory product:

Command	Use it for
djobs setup [host]	Configure MCP and passive lifecycle capture for one supported host
djobs doctor	Check local storage and integrations, with a concrete next action
djobs memory list	See what the current repository remembers
djobs memory search "query"	Find a prior goal, failure, decision, or result
djobs memory status ID stale	Retire outdated memory without erasing its audit trail
djobs memory forget ID	Delete one memory item
djobs memory clear --yes	Clear passive memory for this repository family
djobs gain	Inspect heuristic recovery and verified-task efficiency estimates
djobs pause / djobs unpause	Temporarily disable or resume automatic behavior
djobs receipt	Show an evidence-backed work summary

The original durable job queue engine is retained for compatibility, but it no longer dominates the first-run experience. Its operational commands are available through djobs legacy --help. Direct historical invocations still work for scripts and hooks, with a compatibility notice.

What djobs remembers

A normal coding session can record bounded local observations such as:

Memory type	Example
User intent	“Keep Python 3.10 support.”
Tool result	“Updated src/parser.py; focused tests passed.”
Tool failure	“State normalization removed plus signs.”
Repository change	Tracked, staged, and bounded untracked Git changes
Session capsule	Goal, constraints, progress, failures, and next step

Passive memory never silently claims a task. Explicit ownership is a separate feature for coordinated work that genuinely needs leases and handoff evidence.

Five MCP tools, with clear roles

Tool	Call it when
sync_workspace	Starting or continuing repository work. This is the default recovery entry point.
memory	Inspecting, searching, retiring, forgetting, or clearing passive memory.
checkpoint	Deliberately claiming one bounded unit so another agent does not duplicate it.
handoff	Releasing or completing a claimed unit with bounded evidence.
resume_delta	Maintaining an older integration that already stores correlation IDs and revisions.

Choosing a recovery detail level

Start with sync_workspace(..., context_tier="resume"):

Tier	Use it for	Returned detail
resume	Normal continuation	Goal, constraints, progress, failures, next step, tasks, and Git state
evidence	Checking why a conclusion was selected	Resume capsule plus compact supporting observations
audit	Lifecycle changes or diagnosis	Full memory IDs, timestamps, scores, and audit fields

Persist the returned context_hash and pass it back as known_context_hash on an equivalent later recovery. If passive memory did not change, djobs suppresses repeated observations while still returning current task state.

Install and host support

VS Code / GitHub Copilot

Install the djobs VS Code extension. It registers the compact MCP server and exposes setup, diagnostics, pause, and resume without a permanent sidebar, hosted account, polling service, or cloud database.

CLI-managed hosts

djobs setup copilot
djobs setup codex
djobs setup claude
djobs setup gemini
djobs setup kimi
# or configure all detected hosts:
djobs setup all

Repair and removal use the same vocabulary:

djobs repair codex
djobs remove claude

Generic MCP host

{
  "servers": {
    "djobs": {
      "command": "uvx",
      "args": ["djobs", "mcp"]
    }
  }
}

Storage, privacy, and deletion

• State defaults to ~/.djobs/global.db and stays on the local machine.
• No hosted account, vector database, remote queue, or repository upload is required.
• Sibling Git worktrees share passive repository memory; explicit leases remain checkout-scoped.
• Common API keys, bearer tokens, passwords, authorization values, and URL credentials are redacted on a best-effort basis before storage.
• Add [djobs:no-memory] to skip one prompt.
• Set DJOBS_CAPTURE_USER_INTENT=0 to disable automatic prompt-intent capture.
• Run djobs pause to stop automatic prompt/tool capture, session capsules, repository snapshots, first-call bootstrap, and sync_workspace recovery. Manual memory inspection and deletion remain available; pausing deletes nothing.
• Mark memory resolved, superseded, stale, or contradicted when it should stop influencing normal recovery. Inactive observations remain locally inspectable only while retained by bounded storage; djobs is not a permanent audit archive.
• Use forget for one item or clear --yes for passive memory in the repository family. Explicit checkpoint tasks are preserved by memory clear.
• Hook, search, and storage failures are fail-open and must not block the coding request.

See docs/USER_GUIDE.md for troubleshooting, field meanings, and cleanup examples.

Explicit ownership, only when needed

checkpoint("Implement parser", path="src/parser.py")
  -> this checkout owns one expiring lease

handoff(task_id, "Parser updated; edge tests remain", completed=false)
  -> releases the task with bounded evidence

Do not create a checkpoint for every prompt. Passive observations are enough for ordinary continuation.

Benchmarks

python scripts/benchmark_project_memory.py
python scripts/benchmark_resume_quality.py

Fixture path	Simple serialized-text estimate	Minimum calls
Re-read every bundled synthetic source file	~7,805 tokens	18 file reads
Query-aware sync_workspace resume tier	~224 tokens	1 MCP call

This is a payload-size regression fixture, not an end-to-end savings claim. Its reread baseline assumes every bundled source file is sent again and does not model modern agents that summarize, cache, or selectively read files. Do not interpret the comparison as provider-token savings, billing reduction, latency improvement, or model-quality improvement. Use it to detect changes in djobs payload shape and inspect the benchmark methodology yourself. The companion quality fixture checks cross-worktree recall, checkout ownership isolation, stale-memory exclusion, and unchanged-context replay suppression.

djobs gain complements the fixture with local workflow heuristics:

djobs gain
djobs gain --history
djobs gain --format json

It reports first-pass verified rate, repair attempts, average attempts per verified task, cycle-time proxy, and simple context-size estimates. These are explainable local estimates, not observed model usage or guaranteed savings.

Requirements

Component	Requirement
Python runtime	Python 3.10+; Python 3.10–3.14 tested in CI
VS Code extension	VS Code 1.101 or newer
Storage	Local SQLite by default
Operating systems	Windows, macOS, Linux

Node.js is only required to develop or package the extension.

Development

git clone https://github.com/jhuang-tw/djobs.git
cd djobs
python -m venv .venv
# activate the environment
python -m pip install -e ".[dev,pg]"
pre-commit install

python scripts/preflight.py --profile quick --fix --base-ref origin/main
python scripts/preflight.py --profile full --check --base-ref origin/main

The top-level product is local agent memory. Queue, worker, scheduler, and dashboard modules are a compatibility subsystem; new examples and user documentation should not present them as the default experience. See CONTRIBUTING.md, AGENTS.md, examples/README.md, and docs/RELEASE.md before changing public behavior.

PyPI  ·  VS Code Marketplace  ·  Documentation  ·  Issues

MIT licensed.