Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
CLI Foundation Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Replace placeholder shell scripts with a tested Python CLI foundation for Open Second Brain.
Architecture: The repository will expose a small Python package under src/open_second_brain/. The CLI entrypoint will be open_second_brain.cli:main, with the existing scripts/o2b and scripts/vault-log shell wrappers delegating to Python modules. v0 keeps dependencies to the Python standard library.
Tech Stack: Python 3.11+, argparse, unittest, pathlib, json, datetime, tempfile.
File Structure
- Create
pyproject.toml: package metadata, Python requirement, console scripts for future installers. - Create
src/open_second_brain/__init__.py: package version. - Create
src/open_second_brain/config.py: config path discovery and minimal redacted status model. - Create
src/open_second_brain/event_log.py: append-only daily Markdown event log backend. - Create
src/open_second_brain/cli.py:o2bCLI withstatus,init,doctor,append-event, andexport-configcommands. - Create
src/open_second_brain/vault_log.py: compatibility CLI forvault-log. - Modify
scripts/o2b: shell wrapper that runspython3 -m open_second_brain.cliwith localsrconPYTHONPATH. - Modify
scripts/vault-log: shell wrapper that runspython3 -m open_second_brain.vault_logwith localsrconPYTHONPATH. - Create
tests/test_config.py: config path/status tests. - Create
tests/test_event_log.py: append-only daily Markdown backend tests. - Create
tests/test_cli.py: CLI smoke tests. - Modify
README.md: add CLI development/test commands. - Modify
docs/roadmap.md: mark CLI foundation as in progress/done after implementation.
Task 1: Package Metadata
Files:
Create:
pyproject.tomlCreate:
src/open_second_brain/__init__.pyStep 1: Add package metadata
Create pyproject.toml:
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "open-second-brain"
version = "0.0.1"
description = "Plugin-first second brain package for AI agents and humans."
readme = "README.md"
requires-python = ">=3.11"
license = { text = "MIT" }
authors = [{ name = "Open Second Brain contributors" }]
keywords = ["second-brain", "obsidian", "agents", "skills", "event-log"]
dependencies = []
[project.scripts]
o2b = "open_second_brain.cli:main"
vault-log = "open_second_brain.vault_log:main"
[tool.setuptools.packages.find]
where = ["src"]
Create src/open_second_brain/__init__.py:
"""Open Second Brain core package."""
__version__ = "0.0.1"
- Step 2: Verify metadata imports
Run:
PYTHONPATH=src python3 -c "import open_second_brain; print(open_second_brain.__version__)"
Expected output:
0.0.1
- Step 3: Commit
git add pyproject.toml src/open_second_brain/__init__.py
git commit -m "chore: add python package metadata"
Task 2: Config Discovery
Files:
Create:
src/open_second_brain/config.pyCreate:
tests/test_config.pyStep 1: Write failing config tests
Create tests/test_config.py:
import os
import tempfile
import unittest
from pathlib import Path
from unittest.mock import patch
from open_second_brain.config import default_config_path, discover_config, redact_mapping
class ConfigTests(unittest.TestCase):
def test_default_config_path_uses_env_override(self):
with tempfile.TemporaryDirectory() as tmp:
path = Path(tmp) / "custom.yaml"
with patch.dict(os.environ, {"OPEN_SECOND_BRAIN_CONFIG": str(path)}):
self.assertEqual(default_config_path(), path)
def test_default_config_path_uses_xdg_config_home(self):
with tempfile.TemporaryDirectory() as tmp:
with patch.dict(os.environ, {"XDG_CONFIG_HOME": tmp}, clear=False):
with patch.dict(os.environ, {"OPEN_SECOND_BRAIN_CONFIG": ""}, clear=False):
self.assertEqual(default_config_path(), Path(tmp) / "open-second-brain" / "config.yaml")
def test_discover_config_reports_missing_config(self):
with tempfile.TemporaryDirectory() as tmp:
path = Path(tmp) / "missing.yaml"
result = discover_config(path)
self.assertFalse(result.exists)
self.assertEqual(result.path, path)
self.assertEqual(result.data, {})
def test_discover_config_reads_simple_key_value_yaml(self):
with tempfile.TemporaryDirectory() as tmp:
path = Path(tmp) / "config.yaml"
path.write_text("instance_name: Test Brain\nruntime: hermes\n", encoding="utf-8")
result = discover_config(path)
self.assertTrue(result.exists)
self.assertEqual(result.data["instance_name"], "Test Brain")
self.assertEqual(result.data["runtime"], "hermes")
def test_redact_mapping_redacts_secret_like_keys(self):
redacted = redact_mapping({"api_key": "abc", "path": "/tmp/vault", "token": "xyz"})
self.assertEqual(redacted["api_key"], "[REDACTED]")
self.assertEqual(redacted["token"], "[REDACTED]")
self.assertEqual(redacted["path"], "/tmp/vault")
if __name__ == "__main__":
unittest.main()
- Step 2: Run tests and verify failure
Run:
PYTHONPATH=src python3 -m unittest tests.test_config -v
Expected: FAIL because open_second_brain.config does not exist yet.
- Step 3: Implement config module
Create src/open_second_brain/config.py with:
from __future__ import annotations
import os
from dataclasses import dataclass
from pathlib import Path
from typing import Any
SECRET_KEY_PARTS = ("key", "token", "secret", "password", "credential")
@dataclass(frozen=True)
class ConfigDiscovery:
path: Path
exists: bool
data: dict[str, str]
def default_config_path() -> Path:
override = os.environ.get("OPEN_SECOND_BRAIN_CONFIG")
if override:
return Path(override).expanduser()
config_home = os.environ.get("XDG_CONFIG_HOME")
if config_home:
return Path(config_home).expanduser() / "open-second-brain" / "config.yaml"
return Path.home() / ".config" / "open-second-brain" / "config.yaml"
def parse_simple_yaml(text: str) -> dict[str, str]:
data: dict[str, str] = {}
for raw_line in text.splitlines():
line = raw_line.strip()
if not line or line.startswith("#"):
continue
if ":" not in line:
continue
key, value = line.split(":", 1)
key = key.strip()
value = value.strip().strip('"').strip("'")
if key:
data[key] = value
return data
def discover_config(path: Path | None = None) -> ConfigDiscovery:
resolved = path or default_config_path()
if not resolved.exists():
return ConfigDiscovery(path=resolved, exists=False, data={})
return ConfigDiscovery(path=resolved, exists=True, data=parse_simple_yaml(resolved.read_text(encoding="utf-8")))
def redact_mapping(data: dict[str, Any]) -> dict[str, Any]:
redacted: dict[str, Any] = {}
for key, value in data.items():
lowered = key.lower()
if any(part in lowered for part in SECRET_KEY_PARTS):
redacted[key] = "[REDACTED]"
else:
redacted[key] = value
return redacted
- Step 4: Run tests and verify pass
Run:
PYTHONPATH=src python3 -m unittest tests.test_config -v
Expected: OK.
- Step 5: Commit
git add src/open_second_brain/config.py tests/test_config.py
git commit -m "feat: add config discovery"
Task 3: Event Log Backend
Files:
Create:
src/open_second_brain/event_log.pyCreate:
tests/test_event_log.pyStep 1: Write failing event log tests
Create tests for daily Markdown creation, append-only behavior, explicit date/time, and secret redaction.
- Step 2: Run tests and verify failure
Run:
PYTHONPATH=src python3 -m unittest tests.test_event_log -v
Expected: FAIL because open_second_brain.event_log does not exist yet.
- Step 3: Implement event log module
Implement append_event(vault_dir, agent, message, date, time) with default daily Markdown backend.
- Step 4: Run tests and verify pass
Run:
PYTHONPATH=src python3 -m unittest tests.test_event_log -v
Expected: OK.
- Step 5: Commit
git add src/open_second_brain/event_log.py tests/test_event_log.py
git commit -m "feat: add daily markdown event log backend"
Task 4: CLI Commands
Files:
Create:
src/open_second_brain/cli.pyCreate:
src/open_second_brain/vault_log.pyModify:
scripts/o2bModify:
scripts/vault-logCreate:
tests/test_cli.pyStep 1: Write failing CLI tests
Test o2b status, o2b init, o2b doctor, o2b append-event, and vault-log --as using temporary vault directories.
- Step 2: Run tests and verify failure
Run:
PYTHONPATH=src python3 -m unittest tests.test_cli -v
Expected: FAIL because CLI modules do not exist yet.
- Step 3: Implement CLI modules and wrappers
Use argparse. Keep output stable and plain-text.
- Step 4: Run tests and verify pass
Run:
PYTHONPATH=src python3 -m unittest tests.test_cli -v
Expected: OK.
- Step 5: Run full tests
Run:
PYTHONPATH=src python3 -m unittest discover -s tests -v
Expected: OK.
- Step 6: Commit
git add src/open_second_brain/cli.py src/open_second_brain/vault_log.py scripts/o2b scripts/vault-log tests/test_cli.py
git commit -m "feat: add cli entrypoints"
Task 5: Documentation Update and PR
Files:
Modify:
README.mdModify:
docs/roadmap.mdStep 1: Document development commands
Add commands for running tests and invoking local scripts.
- Step 2: Run full verification
Run:
PYTHONPATH=src python3 -m unittest discover -s tests -v
python3 -m json.tool .claude-plugin/plugin.json >/dev/null
python3 -m json.tool .codex-plugin/plugin.json >/dev/null
python3 -m py_compile plugins/hermes/__init__.py
bash -n scripts/o2b
bash -n scripts/vault-log
Expected: all commands pass.
- Step 3: Commit documentation
git add README.md docs/roadmap.md docs/plans/2026-05-06-cli-foundation.md
git commit -m "docs: add cli foundation plan and usage notes"
- Step 4: Push and open PR
git push -u origin feat/cli-foundation
gh pr create --base main --head feat/cli-foundation --title "feat: add CLI foundation" --body "..."
Self-review
Spec coverage:
- v0 CLI foundation is covered by package metadata, config discovery, event log backend, CLI entrypoints, tests, and documentation.
- Plugin manifests and skills remain in place.
- MCP and deep runtime hooks remain future work.
Placeholder scan:
- The plan includes concrete files, commands, and expected outcomes for every implementation step.
- Implementation followed strict TDD: tests were written and observed failing before production modules were added.
Type consistency:
- Config module names are consistent:
default_config_path,discover_config,redact_mapping. - Event log command names are consistent:
o2b append-event,vault-log --as.