# Neo Cortex — Development Workflow

## Test

```bash
# All tests (217)
cd ~/projects/neo-cortex && uv run pytest -x -q

# Single file
uv run pytest tests/test_timeline_cli.py -x -q
```

## Test timeline_cli (session-start hook output)

```bash
# From source — skip MB to save tokens
cd ~/projects/neo-cortex
CORTEX_DATA_DIR=~/neo-ram uv run python -m neo_cortex.timeline_cli --n 3 --mb /dev/null 2>/dev/null

# From installed global tool (after publish)
CORTEX_DATA_DIR=~/neo-ram neo-cortex-timeline --n 3 --mb /dev/null 2>/dev/null

# With MB (as hook would run it — from a project dir with memory_bank/)
cd ~/neo-ram
CORTEX_DATA_DIR=~/neo-ram neo-cortex-timeline --n 3 2>/dev/null
```

Key flags:
- `--mb /dev/null` — skip Memory Bank output (saves tokens during testing)
- `--n N` — number of recent sessions to show (default 3)
- `--project X` — filter by project name
- `2>/dev/null` — suppress stderr diagnostic logs

## Publish to PyPI

```bash
cd ~/projects/neo-cortex

# 1. Bump version in pyproject.toml
#    version = "X.Y.Z"

# 2. Run tests
uv run pytest -x -q

# 3. Build
rm -rf dist/ && uv build

# 4. Publish
uv publish dist/* \
  --publish-url https://upload.pypi.org/legacy/ \
  --username __token__ \
  --password "$(grep -oP '(?<=password = ).*' ~/neo-ram/.pypi)"

# 5. Update global tool
uv tool upgrade neo-cortex-mcp

# 6. Verify
neo-cortex-timeline --n 1 --mb /dev/null 2>/dev/null
```

Rules:
- PyPI does NOT allow re-uploading same version — must bump
- Token file: `~/neo-ram/.pypi` (ini format, not raw token)
- `uv tool` pins versions — ALWAYS run `uv tool upgrade` after publish

## Entry Points

Defined in `pyproject.toml [project.scripts]`:

| Command | Module | Purpose |
|---------|--------|---------|
| `neo-cortex` | `neo_cortex.server:main` | FastAPI standalone server |
| `neo-cortex-mcp` | `neo_cortex.mcp:main` | MCP server (stdio, used by Claude) |
| `neo-cortex-timeline` | `neo_cortex.timeline_cli:main` | Session-start hook CLI |

## timeline_cli.py — Output Format

Output is MBEL-compressed for token efficiency:

```
§cortex @memories::325 @sessions::115
@projects::neo-console#155+general#38+neo-reloaded#12

§recentWork {last 3 sessions}

[neo-console]
>debug::Continuing tests in UI with default permissions
  +tests are being continued without restart

[general]
>config::Updated DangerouslySkipPermissions to false
  +DangerouslySkipPermissions set to false
  @files::appsettings

# MB::productContext.md
...content...

# MB::systemPatterns.md
...content...
```

Sections:
1. `§cortex` — stats (memory count, session count, top projects)
2. `§recentWork` — last N sessions grouped by project, with summaries/facts/files
3. `# MB::filename` — Memory Bank files in dependency order (product→system→tech→active→progress)

Noise filtering: skips `discussion` activity and `greeting`/`session start`/`introduction` topics.

## Data Directory Discovery

timeline_cli finds its data in this order:
1. `--data-dir` flag
2. `CORTEX_DATA_DIR` env var
3. `{cwd}/.neo/cortex/data` (if has cortex_db/)
4. `~/neo-ram` (if has cortex_db/)

MB path discovery (CWD = project root first):
1. `--mb` flag
2. `{cwd}/memory_bank/` (project root — primary)
3. `{data_dir}/memory_bank/`
