DeepSleep-beta

DeepSleep is the open-source background agent for local models. It gives developers a ds workflow, a compact 3-layer memory file, and idle-time "dreaming" that summarizes recent work while they are away.

---

🐣 The Dumbest Guide (Read this if you're lost)

What is this?

Imagine you're coding. You take a coffee break. You come back and forget what you were doing. DeepSleep was watching your files while you were gone. It "dreamed" about your changes and wrote a summary. Now you just ask ds > What was I working on? and it tells you. It's like a brain for your folder.

How to use (The 3-step shuffle)

1. Init: Open your terminal in your project folder and type ds init. This makes a tiny hidden brain folder (.deepsleep).
2. Dream: Run ds dream in a corner of your screen. It just sits there. When you stop typing for a bit, it writes down what you did.
3. Chat: Type ds whenever you want to talk to your code. Ask things like "Where did I leave that API key?" or "What's next?"

How to deal with errors ️

• "Ollama not found": You need Ollama running. It's the engine. Download it, run it, and try again.
• "Permission Denied": DeepSleep needs to write its memory file. Make sure you have permission to write in the current folder.
• "Stuck dreaming": If ds dream isn't doing anything, make sure you actually saved some files. It only dreams when things change!
• "Garbage answers": Local models can be silly. Type /memory to see what it actually remembers. If it's wrong, you can just tell it!

---

🎯 v1.0 Production-Grade Features (New!)

We've hardened DeepSleep for enterprise-level monorepos:

• 🔒 Atomic Security: FileLock prevents memory corruption even if you run multiple ds instances.
• 🛡️ Path Traversal Sandbox: DeepSleep is now locked to your project root. It will never leak your .ssh or .env files to the AI.
• 📂 Gitignore-Aware: It respects your .gitignore perfectly. No more indexing node_modules or dist garbage.
• ⚡ Incremental Indexing: Uses a local SQLite index to track millions of files instantly without slowing down your machine.
• 🔐 At-Rest Encryption: Use ds init --encrypt to protect your project memory with a password (AES-256).
• 📝 Structured Observability: Now with structlog for clean, machine-friendly logs and a ds health command.

---

Why it lands fast

• pip install deepsleep-ai
• ds init
• ds
• ds dream

That is the product.

You initialize a repo once, ask natural questions in the terminal, and let DeepSleep update session context after you stop typing.

Core promise

• Zero-cost agent: runs on local Ollama models instead of paid tokens
• Idle-time dreaming: watches your repo and summarizes after inactivity
• 3-layer memory: project, session, and ephemeral
• Terminal-native: hacker-style interactive UI with file completion

Search-friendly positioning

DeepSleep is best described as:

• an open-source AI coding agent
• a local AI developer tool
• a background agent for codebases
• a terminal copilot for Ollama
• a local-model alternative to hosted coding assistants

Quick demo

pip install deepsleep-ai
ollama pull deepseek-r1
ds init
ds dream --once
ds

Then ask:

What was I doing?
Refactor src/deepsleep_ai/cli.py
Summarize the recent changes

3-layer memory architecture

DeepSleep explicitly implements a 3-layer memory stack:

• project: long-term repo identity, goals, and facts
• session: what you were doing recently, which files were active, and the latest dream summary
• ephemeral: last turns, open questions, and the most recent file changes

All of it lives in .deepsleep/memory.json, and the compactor keeps that file under 2KB so it stays fast, deterministic, and portable.

Zero-cost local model stack

DeepSleep is built for Ollama and targets deepseek-r1 by default.

If Ollama is offline, DeepSleep still works with deterministic local fallbacks so demos do not collapse and the tool remains usable on day one.

Idle-time dreaming

Run ds dream, leave your editor open, and DeepSleep watches your project for file saves.

After 5 minutes of inactivity, it:

1. collects the files you touched
2. reads compact local snippets
3. writes a fresh session summary into memory
4. preserves only the highest-signal context under the 2KB cap

Install

PyPI

pip install deepsleep-ai

Quick check:

ds --version
ds health

Local development

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Ollama

ollama serve
ollama pull deepseek-r1

Commands

ds init          # Start a new brain for your project
ds init --encrypt # Start a password-protected brain
ds               # Start chatting
ds chat          # Alias for ds
ds dream         # Start the background watcher
ds dream --once  # Run one dream cycle right now
ds status        # Peek inside the brain
ds health        # Check if everything is setup correctly

Package layout

• cli.py: Typer entrypoint and Prompt Toolkit UI
• watcher.py: Watchdog-based idle watcher and dream loop
• memory_manager.py: layered memory store with 2KB compaction
• llm_client.py: Ollama connector with safe local fallback
• config.py: Pydantic-powered configuration management

---

🤝 Contributing

We love builders! If you want to make DeepSleep even better:

1. Check the Roadmap: See what we're building in ROADMAP.md.
2. Read the Guide: Hop into CONTRIBUTING.md for setup steps.
3. Open an Issue: Found a bug? Tell us!
4. Pull Requests: Send your code. We're fast at reviewing.

Note: Please ensure all tests pass (pytest) before submitting!

---

Trust signals

• publishable pyproject.toml for pip install deepsleep-ai
• ds console entrypoint
• MIT license
• GitHub Actions CI
• tests for memory compaction, watcher behavior, offline fallback, and chat exit flow
• live PyPI package: deepsleep-ai

Self-test

pytest -v
python -m deepsleep_ai --help
python -m build --no-isolation

---

There is a practical launch playbook in LAUNCH.md, a contributor guide in CONTRIBUTING.md, release instructions in RELEASING.md, and a project history in CHANGELOG.md.