Metadata-Version: 2.4
Name: djobs
Version: 0.18.2
Summary: Local project memory that helps coding agents continue work across AI sessions.
Project-URL: Homepage, https://jhuang-tw.github.io/djobs/
Project-URL: Repository, https://github.com/jhuang-tw/djobs
Project-URL: Documentation, https://jhuang-tw.github.io/djobs/
Project-URL: Issues, https://github.com/jhuang-tw/djobs/issues
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,coding-agent,context-recovery,cross-agent-handoff,local-agent-memory,model-context-protocol,repository-memory,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: mcp[cli]<2,>=1.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.5; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff==0.15.14; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: pg
Requires-Dist: psycopg[binary]>=3.1; extra == 'pg'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.jhuang-tw/djobs -->

<p align="center">
  <img src="https://raw.githubusercontent.com/jhuang-tw/djobs/main/vscode-ext/media/icon-128.png" width="88" alt="djobs logo">
</p>

<h1 align="center">djobs</h1>

<p align="center">
  <strong>Local project memory for AI coding agents.</strong><br>
  Continue the repository instead of explaining it again in every new session.
</p>

<p align="center">
  <a href="https://github.com/jhuang-tw/djobs/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/jhuang-tw/djobs/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://pypi.org/project/djobs/"><img alt="PyPI" src="https://img.shields.io/pypi/v/djobs.svg"></a>
  <a href="https://pypi.org/project/djobs/"><img alt="Python 3.10–3.14" src="https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white"></a>
  <a href="https://marketplace.visualstudio.com/items?itemName=jhuang-tw.djobs"><img alt="VS Code Marketplace" src="https://img.shields.io/visual-studio-marketplace/v/jhuang-tw.djobs?label=VS%20Code"></a>
  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
</p>

## See it work in 60 seconds

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

```bash
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`. The extension and
`djobs setup` use user-level registration, while the shared local database is created on first use.

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

```json
{
  "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:

```text
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 recovery savings and verified-task efficiency |
| `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](https://marketplace.visualstudio.com/items?itemName=jhuang-tw.djobs)**.
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

```bash
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:

```bash
djobs repair codex
djobs remove claude
```

### Generic MCP host

```json
{
  "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.
- Mark memory `resolved`, `superseded`, `stale`, or `contradicted` when it should stop influencing
  normal recovery.
- 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](docs/USER_GUIDE.md) for troubleshooting, field meanings, and cleanup examples.

## Explicit ownership, only when needed

```text
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

```bash
python scripts/benchmark_project_memory.py
python scripts/benchmark_resume_quality.py
```

| Recovery strategy | Estimated context | 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 |

The bundled fixture reports a **97.1% recovery-payload proxy reduction**. It is a reproducible
synthetic comparison, not provider billing, latency, or model-quality measurement. The quality
benchmark also checks cross-worktree recall, checkout ownership isolation, stale-memory exclusion,
and unchanged-context replay suppression.

`djobs gain` complements the synthetic benchmark with local workflow proxies:

```bash
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 estimated context tokens per verified task.

## 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

```bash
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.

<p align="center">
  <a href="https://pypi.org/project/djobs/"><strong>PyPI</strong></a>
  &nbsp;·&nbsp;
  <a href="https://marketplace.visualstudio.com/items?itemName=jhuang-tw.djobs"><strong>VS Code Marketplace</strong></a>
  &nbsp;·&nbsp;
  <a href="https://jhuang-tw.github.io/djobs/"><strong>Documentation</strong></a>
  &nbsp;·&nbsp;
  <a href="https://github.com/jhuang-tw/djobs/issues"><strong>Issues</strong></a>
</p>

<p align="center">MIT licensed.</p>
