Metadata-Version: 2.4
Name: living-brain
Version: 0.1.0
Summary: Living Brain — agent-native CLI for a markdown-backed personal knowledge and task store.
Project-URL: Homepage, https://github.com/Habibi-7/living-brain
Project-URL: Repository, https://github.com/Habibi-7/living-brain
Project-URL: Issues, https://github.com/Habibi-7/living-brain/issues
Author-email: Habibi-7 <khairullahhabib744@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,claude,cli,knowledge-management,llm,markdown,notes,second-brain
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.9
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: python-ulid>=3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.24.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# brain — Living Second Brain (MVP)

Agent-native CLI for a markdown-backed event store. See [`CONTEXT.md`](./CONTEXT.md) for the product vision and principles.

This is the MVP covering the two foundational pieces: the **capture path + event schema**, and the **timeline retrieval surface**.

## Install

```bash
uv sync                 # create .venv and install deps
uv pip install -e .     # install the `brain` CLI into the venv
source .venv/bin/activate
```

Or with pip:

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

## Quickstart

```bash
brain init ./my-vault               # scaffold a vault
export BRAIN_DIR=./my-vault          # point the CLI at it (or use --vault)

brain add "reviewed the hugentobler essay" --type note --tags research,agents
echo "use ULID for event ids" | brain add --type decision
brain add --file notes/meeting.md --type note

brain timeline --last 7d             # recent events
brain timeline --format md --write   # writes renders/timelines/<range>.md
```

## CLI contract (for agents)

Every command returns a JSON envelope when an agent is detected (`--agent` flag, or env var: `CLAUDECODE`, `CURSOR_TRACE_ID`, `COPILOT_AGENT_ENABLED`, `AIDER_*`, `OPENCODE`). Humans get a clean text view; under the hood it's the same data.

### Success envelope

```json
{
  "ok": true,
  "command": "brain add",
  "result": { "...": "command-specific payload" },
  "next_actions": [
    { "command": "brain show <id>", "description": "...",
      "params": { "id": { "value": "01K..." } } }
  ],
  "metrics": { "duration_ms": 34, "cost_usd": 0.0 }
}
```

### Error envelope

```json
{
  "ok": false,
  "command": "brain add",
  "error": { "code": "INVALID_TYPE", "message": "...", "retryable": false },
  "fix": "plain-language suggested fix",
  "next_actions": [ ... ],
  "metrics": { "duration_ms": 3, "cost_usd": 0.0 }
}
```

### Exit codes

- `0` — success
- `2` — validation / user error (retryable=false)
- `3` — transient / retryable error
- `4` — vault not found / not initialized
- `1` — unexpected error

## Event file shape

```
vault/
├── events/YYYY/MM/DD/<ulid>-<slug>.md
├── renders/timelines/<range>.md
├── audit/YYYY-MM-DD.jsonl
└── .brain/
    ├── config.toml
    └── cache.sqlite          # derivative, rebuildable with `brain reindex`
```

An event file:

```markdown
---
id: 01K...ULID
schema: 1
type: note
created_at: 2026-04-24T14:32:11Z
ingested_at: 2026-04-24T14:32:12Z
source: cli
agent: unknown
tags: [research, agents]
links: []
hash: sha256:...
---

the actual markdown body
```

## Event types (v0)

`note` · `task` · `decision` · `fact` · `link`

Add via `--type`. Classification subagent is deferred; current MVP requires explicit type (or defaults to `note`).

## Development

```bash
uv run pytest          # run the test suite
uv run ruff check      # lint
uv run ruff format     # format
```
