djobs 0.16.0

Local project memory that helps coding agents continue work across AI sessions.

djobs — project memory for coding agents

Stop explaining the same project every time you open a new AI session.

Yesterday your coding agent read the repository, tried a fix, found why the tests failed, and changed several files. Today the chat is gone or the context was compacted, so it starts over.

djobs keeps a small, local memory for each Git repository so the next session can recover:

• what you asked for and which constraints matter;
• which tools succeeded or failed;
• what changed in the working tree;
• a compact end-of-session capsule with the goal, progress, failures, and next step.

It searches those memories using the current request instead of blindly replaying the latest chat history. Memory stays in local SQLite. No account, hosted service, or project upload is required.

What continuing work looks like

Session 1
You: Fix the OAuth callback loop. Keep the public auth API and preserve '+' in state.
Agent: pytest failed because normalization removed '+'.
Agent: updated src/auth/callback.py; one integration test remains.
[context compacts or the session closes]

Session 2
You: Continue the OAuth fix.
Agent receives from djobs:
- Goal: fix the OAuth callback loop without changing the public auth API
- Failed: state normalization removed '+'
- Progress: callback parser updated; integration test remains
- Current Git changes

The recovered text is data, not an instruction. The coding agent still follows your current request.

Install once, then open any repository

The easiest route for VS Code / GitHub Copilot users is the VS Code extension. It registers the local MCP server without adding a sidebar or background polling UI.

For another MCP host, add this server once:

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

After the MCP is present, normal Vibe Coding needs no per-project command and no setup wizard. The first djobs tool call creates ~/.djobs/global.db, identifies the current Git repository, and installs only the detected host's passive lifecycle adapter. Opening another repository uses a different local memory automatically.

djobs setup and djobs doctor remain available only for manual repair or diagnostics in headless environments.

What is saved automatically

Memory	Example	Changes task ownership?
User intent	“Keep Python 3.10 support; do not replace Zustand.”	No
Tool result	“edit completed — src/parser.py — fallback parser updated”	No
Tool failure	“pytest failed — state normalization removed plus signs”	No
Git observation	Actual tracked, staged, and bounded untracked changes	No
Session capsule	Goal, recent progress, failures, and next step	No

Exact duplicate prompts in the same session are ignored. Before context compaction and at real session end, djobs creates a deterministic capsule without calling an external model or sending repository content anywhere.

Relevant memory, not just recent memory

Agents should call:

sync_workspace(query="the user's current request")

The query searches repository-scoped memory with SQLite FTS5 when available and a portable bounded fallback otherwise. Older relevant constraints and failed approaches can therefore rank above newer unrelated activity.

You can also ask the agent naturally:

What does djobs remember about the OAuth bug?
Forget the memory about the abandoned Redis experiment.
Clear djobs memory for this repository.

The MCP exposes a memory tool for list, search, forget, and confirmed clear actions. Clearing passive memory does not delete explicit tracked tasks.

Terminal equivalents are available when useful:

djobs memory list
djobs memory search "OAuth callback"
djobs memory forget MEMORY_ID
djobs memory clear --yes

Privacy controls

• State is stored locally in ~/.djobs/global.db by default.
• Common API keys, bearer tokens, passwords, authorization values, and URL credentials are redacted on a best-effort basis before storage.
• Put [djobs:no-memory] in a prompt to skip that prompt.
• Set DJOBS_CAPTURE_USER_INTENT=0 to disable automatic prompt-intent memory.
• Use memory(action="forget", memory_id="...") to delete one record.
• Use confirmed memory(action="clear") to clear passive memory for the current repository.
• Stored content is always treated as untrusted data, never executable instructions.
• Hook, search, or storage failures are fail-open and never block the coding request.

Recovery-payload benchmark

The repository includes a deterministic proxy benchmark:

python scripts/benchmark_project_memory.py

With its default synthetic 18-file fixture, the current implementation compares:

Recovery strategy	Estimated context	Minimum calls
Re-read every synthetic source file	~7,805 tokens	18 file reads
Query-aware sync_workspace	~407 tokens	1 MCP call

That is a 94.8% recovery-payload proxy reduction for this fixture. It is intentionally not presented as provider billing, latency, or model-quality measurement. The script is included so results can be reproduced and challenged instead of treated as a marketing claim.

Supported local hosts

Host	Prompt-aware memory	Lifecycle observations	Local configuration
GitHub Copilot CLI + VS Code Agent	UserPromptSubmit	session, tool, compact, end	~/.copilot/hooks/djobs.json
Claude Code	UserPromptSubmit	session, tool, compact, end	~/.claude/settings.json
Gemini CLI	BeforeAgent	session, tool, compress, end	~/.gemini/settings.json
Kimi Code	UserPromptSubmit	session, tool, compact, end	~/.kimi-code/config.toml
Codex	Query-aware MCP recovery	supported native session/tool hooks	~/.codex/hooks.json

Only djobs-managed entries are replaced or removed. Malformed configuration is never overwritten automatically. An unidentified host still gets repository-scoped MCP memory; djobs simply avoids guessing which hook file to modify.

Python 3.10+ is supported on Windows, macOS, and Linux.

Default MCP tools

The normal server deliberately stays small:

Tool	Purpose
sync_workspace(query?, ...)	Recover relevant goals, failures, capsules, tasks, and Git observations under a token budget.
memory(action, ...)	Inspect, search, forget, or explicitly clear passive memory for the current repository.
checkpoint(summary, ...)	Explicitly create or resume one tracked unit of work.
handoff(task_id, ...)	Explicitly release or complete tracked work with bounded evidence.
resume_delta(correlation_id, ...)	Backward-compatible revision recovery for integrations already storing IDs.

Lower-level queue and worker tools remain opt-in through djobs-mcp-full.

Advanced: explicit ownership and handoff

Passive memory never creates or claims tasks. Ownership changes only through explicit checkpoint and handoff calls:

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

handoff(task_id, "Parser updated; edge tests remain", completed=false)
  -> releases the work with evidence for a later session

Automatic adapters may heartbeat a task already owned by the same session, but they never:

• turn every prompt into a task;
• claim pending work at startup;
• infer completion from natural-language output;
• release work when a model turn merely stops;
• overwrite another client's lease.

This explicit layer is optional for people who only need project memory.

Repository identity and storage

Repository resolution uses MCP roots, host cwd, the enclosing Git root, and finally process cwd. Windows paths, WSL mounts, and common Git Bash spellings resolve to compatible identities.

Default database:

~/.djobs/global.db

Override it with DJOBS_DB. A repository-specific database is also supported with djobs mcp --db .djobs/state.db; do not commit the database.

Each repository retains at most 1,000 recent visible observations by default. Git contents are hashed for change detection and are not stored as observation text.

Development

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

ruff check src/ tests/
ruff format --check src/ tests/
mypy
pytest -q
python -m build
python -m twine check dist/*

cd vscode-ext
npm ci
npx tsc -p ./ --noEmit
npm run compile

See CONTRIBUTING.md and AGENTS.md before changing public behavior.

License

MIT