Metadata-Version: 2.4
Name: clear-mind
Version: 0.1.5
Summary: An AI companion that grows alongside you through your Obsidian notes
Project-URL: Homepage, https://github.com/slow-coding/clear_mind
Project-URL: Repository, https://github.com/slow-coding/clear_mind
Project-URL: Issues, https://github.com/slow-coding/clear_mind/issues
Author: Clear Mind Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,entropy-reduction,langgraph,local-first,obsidian
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Text Processing
Requires-Python: >=3.12
Requires-Dist: deepagents>=0.4.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain-openai>=0.3.0
Requires-Dist: langgraph-checkpoint-sqlite>=2.0.0
Requires-Dist: langgraph>=0.4.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: schedule>=1.2.0
Requires-Dist: typer>=0.15.0
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

  Clear Mind Banner

# Clear Mind

[中文文档](https://github.com/slow-coding/clear_mind/blob/main/README_CN.md)

  Clear Mind Demo

**You and an AI co-manage one Obsidian vault — with crystal-clear boundaries.**

Clear Mind reads your notes, understands who you are, and grows alongside you. It remembers your patterns, tracks your growth, and suggests entropy reduction. But it **never touches your notes** — all its writing is confined to its own folder, enforced at the code level.

This is not another AI that dumps files into your vault. Clear Mind is a disciplined co-manager that knows its place.

## Core Philosophy: Co-manage, Don't Pollute

Most AI tools write files everywhere, cluttering your carefully curated vault. Clear Mind is different:

```
Your Obsidian Vault
├── daily-notes/       ← Your notes. Sacred. Read-only for the agent.
├── projects/          ← The agent observes, understands, but NEVER modifies.
├── ideas/             ← Your creative space remains yours.
│
└── _clear_mind/       ← Agent's space. Only here it writes.
    ├── about_user.md      Growing understanding of you
    ├── knowledge_rules.md Rules learned about your note system
    ├── entropy_log.md     Entropy reduction observations
    ├── reflections/       Daily reflections on what changed
    └── ...
```

**The boundary is not just a prompt — it's enforced in code:**

- `write_agent_note` and `append_agent_note` validate the path starts with `_clear_mind/`
- Path traversal attempts are blocked (`../../etc/passwd` → rejected)
- The agent has zero write tools that operate outside `_clear_mind/`
- Even if the LLM "decides" to write elsewhere, the tool layer refuses

**What the agent DOES do:**

- Read your notes to understand your thinking, projects, and patterns
- Build a growing profile in `_clear_mind/about_user.md` — so it remembers you across sessions
- Write daily reflections in `_clear_mind/reflections/` — tracking what changed and what it means
- Log entropy reduction opportunities in `_clear_mind/entropy_log.md` — suggestions, never actions

**What the agent NEVER does:**

- Modify, delete, or rearrange your notes
- Create files outside `_clear_mind/`
- Act on suggestions without your explicit consent

## Features

- **Local-first** — runs on LM Studio, Ollama, or any OpenAI-compatible API. Zero cloud dependency.
- **Obsidian CLI integration** — uses the official Obsidian CLI (v1.12+) for all vault operations
- **Hard boundary enforcement** — the agent physically cannot write outside `_clear_mind/`, enforced at the tool level, not just the prompt
- **Human-in-the-loop** — write operations require your approval before execution (approve/reject)
- **Streaming output** — agent responses render progressively, no waiting for full completion
- **Anti-hallucination** — agent must verify facts from the vault before claiming to know anything about you
- **Heartbeat monitoring** — daily vault change detection with zero token cost when nothing changed
- **Incremental growth** — `about_user.md` grows with every interaction, building real institutional memory
- **Learned rules** — agent writes knowledge base rules to `knowledge_rules.md` as it learns your system

## Quick Start

### Prerequisites

- Python 3.12+
- [Obsidian](https://obsidian.md) desktop app running (v1.12+ with CLI enabled)
- A local LLM server (e.g. [LM Studio](https://lmstudio.ai), [Ollama](https://ollama.com))

### Install

```bash
pip install clear-mind
```

### Setup

```bash
clear-mind init
```

Interactive setup will ask for:
1. Your Obsidian vault path
2. LLM API base URL (default: `http://localhost:1234/v1`)
3. API key (default: `lm-studio`)
4. Model name (default: `qwen3.5-9b`)

This creates a `.env` file and initializes the `_clear_mind/` folder in your vault.

If you `cd` into your Obsidian vault directory first, `init` will auto-detect it.

#### Example: LM Studio with Qwen 3.5

1. Download [LM Studio](https://lmstudio.ai), search and load `unsloth/qwen3.5-35b-a3b`
2. Start the local server (default port 1234)
3. Run:

```bash
clear-mind init
```

When prompted:
```
Obsidian vault path: /Users/you/MyVault
LLM base URL [http://localhost:1234/v1]:       ← press Enter
API key [lm-studio]:                            ← press Enter
Model name [qwen3.5-9b]: unsloth/qwen3.5-35b-a3b
```

Or configure via `.env` directly:

```env
CLEAR_MIND_VAULT_PATH=/Users/you/MyVault
CLEAR_MIND_BASE_URL=http://localhost:1234/v1
CLEAR_MIND_API_KEY=lm-studio
CLEAR_MIND_MODEL_NAME=unsloth/qwen3.5-35b-a3b
```

Then start chatting:

```bash
clear-mind chat
```

### Chat

```bash
clear-mind chat
```

Start an interactive conversation. The agent can read your notes, search your vault, and write reflections — but only within its own folder.

**Chat controls:**
- `Enter` — send message
- `Ctrl+O` — insert newline (multi-line input)
- `ESC` — cancel current input (stays in conversation)
- `Ctrl+D` — exit conversation
- `/clear` — reset session (clear conversation history, start fresh)
- `exit`, `quit` — exit

When the agent wants to write to `_clear_mind/`, you'll be prompted to approve or reject the action.

### Heartbeat

Single run (e.g. via cron):

```bash
clear-mind heartbeat
```

Long-running daemon:

```bash
clear-mind serve
```

The heartbeat scans for vault changes since the last run. If nothing changed, it exits immediately (zero token cost). If changes are detected, the agent reads the changed notes and updates its understanding.

### Diagnose

```bash
clear-mind doctor
```

Checks your configuration, vault structure, Obsidian CLI availability, and model connection.

## Configuration

All settings are loaded from a `.env` file or environment variables with the `CLEAR_MIND_` prefix:

| Variable | Default | Description |
|---|---|---|
| `CLEAR_MIND_VAULT_PATH` | *(required)* | Path to your Obsidian vault |
| `CLEAR_MIND_BASE_URL` | `http://localhost:1234/v1` | LLM API base URL |
| `CLEAR_MIND_API_KEY` | `lm-studio` | API key |
| `CLEAR_MIND_MODEL_NAME` | `qwen3.5-9b` | Model to use |
| `CLEAR_MIND_HEARTBEAT_CRON` | `0 9 * * *` | Heartbeat schedule (daily at 9am) |
| `CLEAR_MIND_CHECKPOINTER_PATH` | *(auto: vault's `_clear_mind/`)* | State persistence path |

### Reset Agent Memory

```bash
clear-mind reset
```

Clears the checkpoint database and resets `_clear_mind/` files to initial templates. Use this when switching vaults or starting fresh.

## Real-World Example

The following is actual output from Clear Mind running with LM Studio + `unsloth/qwen3.5-35b-a3b` on a test vault with 4 notes.

### Heartbeat: Automatic Reflection

Your notes in the vault:
```markdown
daily/2026-03-28.md — "今天开始研究 gRPC，感觉流式传输比 REST 优雅很多。下周做 POC。
                      读了《思考快与慢》第 12 章，关于过度自信的偏见。"
daily/2026-03-29.md — "决定在项目里用 gRPC 替换 REST。流式 API 正好解决了实时推送的需求。
                      发现 Obsidian 标签命名不一致，需要统一。"

projects/distributed-system.md  — notes on CAP theorem, Raft/Paxos, message queues
projects/decision-framework.md  — methodology: boundaries → options → score → POC → rollback
```

After `clear-mind heartbeat`, the agent reads all changed notes and writes:

**`_clear_mind/about_user.md`** — Evolving user profile:
```markdown
## Technical Focus
- Studying distributed systems: CAP theorem, consistency models, consensus algorithms
- Currently focused on gRPC for microservices, particularly streaming RPC
- Decided to replace REST with gRPC due to real-time push requirements
- Uses a structured decision framework: define boundaries → list options → score → POC → rollback

## Learning Habits
- Self-reflective about cognitive biases in coding ("this is simple" leading to debugging hell)
- Plans POCs before full adoption
```

**`_clear_mind/reflections/2026-03-29.md`** — Daily reflection:
```markdown
## What Changed
The user made a concrete decision to migrate from REST to gRPC.
They didn't just switch because gRPC is "cooler" — they followed their
own methodology: identified the need (streaming), evaluated tradeoffs
(learning cost acceptable), and planned a POC before full migration.

There's a nice parallel between their technical work and personal growth:
studying overconfidence bias while simultaneously being disciplined enough
to do a POC rather than diving in headfirst.

## No Major Entropy Issues
The tag naming inconsistency is already on their TODO list — user is
aware and will address when ready.
```

**`_clear_mind/entropy_log.md`** — Entropy tracking:
```markdown
## 2026-03-29: Tag Naming Inconsistency (Already Logged)
User noted tag system has mixed Chinese/English naming conventions.
Already on their TODO list. No action needed from agent.
```

### Chat: Interactive Q&A

```
You: 请读一下 daily/2026-03-29.md 然后告诉我你了解到了什么

Clear Mind: 从这篇日记中我了解到：
  • 决定在项目里用 gRPC 替换 REST，因为流式 API 能解决实时推送的需求
  • 在整理 Obsidian 的标签系统，发现了中英文混用的问题
  • 计划读《系统之美》第三章

  看起来你今天做了两个重要的决定：技术架构升级和知识管理系统优化。
  这两个都是熵减的好方向！
```

## Clear Mind vs Claude Code + Obsidian

| | Clear Mind | Claude Code + Obsidian |
|---|---|---|
| **Runtime** | Standalone CLI agent, runs locally or as a daemon | IDE extension, requires editor session |
| **LLM** | Local-first (LM Studio, Ollama) | Cloud API (Anthropic, OpenAI) |
| **Obsidian integration** | Purpose-built Obsidian CLI tools (14 tools) | Generic file read/write |
| **Write boundary** | Hard enforced: agent can only write to `_clear_mind/`, with human approval | No boundary: can write anywhere |
| **Heartbeat** | Built-in: detects vault changes, runs automatically | No automatic scanning |
| **State** | Persistent across sessions (SQLite checkpointer) | Per-session, no cross-session memory |
| **Cost** | Zero after setup (local model) | Per-token API cost |

## Architecture

```
clear_mind/
├── cli.py          Typer CLI (init, chat, heartbeat, serve, doctor, reset)
├── agent.py        DeepAgents SDK agent assembly + streaming chat loop
├── input_handler.py Multi-line input with ESC cancellation
├── hitl.py         Human-in-the-loop tool approval
├── obsidian.py     Obsidian CLI tools (14 tools: read, search, write...)
├── config.py       pydantic-settings configuration
├── heartbeat.py    Vault change scanning + scheduling
└── prompts.py      System prompts (identity, boundaries, anti-hallucination)
```

The agent is assembled with [DeepAgents SDK](https://github.com/langchain-ai/deepagents) on top of [LangGraph](https://github.com/langchain-ai/langgraph), using a SQLite checkpointer for state persistence across sessions.

## License

MIT
