Local repository memory over MCP

Continue the repository. Skip the re-explanation.

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

Install for VS Code View on PyPI

✓ MIT licensed ✓ Local SQLite ✓ Python 3.10–3.14 ✓ No hosted account

Animated djobs checkpoint and crash-recovery demo

Works locally with GitHub Copilot Claude Code Codex Gemini CLI Kimi Code Any MCP host

Why djobs

Stop paying the restart tax on every new chat.

A coding agent may already know the failed approach, the project constraint, the remaining test, and the exact files it changed. djobs keeps that context attached to the repository instead of the chat window.

Local-first memory

Goals, observations, structured session capsules, and task state stay in local SQLite. No broker, daemon, cloud database, or hosted login.

Relevant recall

The current request searches older memory, so a useful constraint or failed approach can rank above newer unrelated activity.

Worktree-aware handoff

Sibling worktrees share passive repository memory while explicit ownership and leases stay isolated to each checkout.

How it works

Capture, search, continue.

Ordinary sessions use passive memory. Exact task ownership remains explicit, so observation never silently becomes control.

Capture the session

Bounded user intent, tool results, failures, Git changes, and a deterministic structured capsule are stored as local data.

Search for the request

sync_workspace(query=..., context_tier="resume") retrieves relevant repository memory under a token budget.

Continue with evidence

The agent resumes useful state and can checkpoint or hand off exact work only when coordination requires it.

Layered recovery

Pay only for the detail the session needs.

The MCP defaults to the smallest continuation capsule. Deeper evidence and full audit detail remain available when requested.

resume

Normal continuation

Goal, constraints, progress, failures, next step, task state, and Git state.

evidence

Supporting context

The resume capsule plus compact observations without memory IDs or timestamps.

audit

Diagnosis and lifecycle

Full identifiers, timestamps, and memory detail for debugging or status updates.

Clear boundaries

Memory is not task ownership.

djobs separates what the repository remembers from who owns a unit of work.

Passive project memory

Best for normal coding sessions and context recovery.

user goals and constraints
successful and failed tool results
Git working-tree observations
structured session capsules and memory lifecycle states
query-aware recall with unchanged-context suppression

Explicit checkpoint and handoff

Best for coordinated tasks that need exact ownership.

checkout-scoped leases
bounded completion or release evidence
safe worktree isolation
no silent prompt-to-task conversion
lower-level queue tools available only when requested

Install once

Open any repository and continue.

The VS Code extension is the easiest route. Its first MCP call may create the local database and configure the detected Copilot adapter at user level; Diagnose Setup makes that visible. Other MCP hosts can launch djobs through uvx.

Python 3.10+Python 3.10–3.14 tested in CI

VS Code 1.101+For the Marketplace extension

Node.js 20+Only for extension development

setup

# VS Code / GitHub Copilot
Install: djobs — Local Agent Memory

# Any MCP host
uvx djobs mcp

# Manual repair only
pipx install djobs
djobs setup
djobs doctor

Five compact MCP tools

Small surface, clear responsibility.

Passive memory stays lightweight. Lower-level queue and worker tools remain available through djobs-mcp-full.

sync_workspace(...)

Recover a minimal continuation capsule, compact evidence, or full audit detail under a token budget.

memory(...)

List, search, deactivate, forget, or explicitly clear passive repository memory.

checkpoint(...)

Deliberately create or resume one checkout-scoped unit of work.

handoff(...)

Release or complete tracked work with bounded evidence.

resume_delta(...)

Compatibility path for integrations that already persist revision IDs.

Reproducible benchmarks

Measure payload shape, not a marketing percentage.

The bundled deterministic fixture compares a deliberately simple full-reread baseline with one query-aware resume-tier response.

~7,805simple estimate for rereading all 18 synthetic files

~224simple estimate for one query-aware sync_workspace resume response

This is a payload-size regression fixture, not an end-to-end savings claim. The baseline does not model modern agents that summarize, cache, or selectively read files. It is not provider billing, measured model usage, latency, or quality. Run python scripts/benchmark_project_memory.py and inspect the assumptions.

djobs gain reports local task-efficiency and context-size heuristics. Treat them as explainable estimates, not guaranteed savings.

Privacy and control

Local, inspectable, and reversible.

State defaults to ~/.djobs/global.db. Pause stops automatic capture and recovery without deleting data. Common credentials are redacted on a best-effort basis, stored text is untrusted data, retention is bounded, and failures remain fail-open.

Opt out per prompt

Add [djobs:no-memory] for one prompt or set DJOBS_CAPTURE_USER_INTENT=0 globally.

Retire without selecting

Mark memory resolved, superseded, stale, or contradicted. It remains inspectable only while retained by bounded local storage.

Forget or clear

Delete one memory or explicitly clear passive memory for the repository family.

Give the repository a memory that survives the chat.

Open source, MIT licensed, local by default, and designed for coding agents that need to continue real work without replaying the entire project.

Install the extension Read the source