Skip to content

An always-on second brain you talk to. Voice notes in Telegram → typed, linked knowledge in your Obsidian vault. Runs 24/7 on the Claude subscription you already have.

feat(persona)!: conversational agent identity + conditional marker contract

smixse03dfd53cb0d
diff --git a/deploy/brain-system.md b/deploy/brain-system.md
index 24512cc..7dbca36 100644
--- a/deploy/brain-system.md
+++ b/deploy/brain-system.md
@@ -1,30 +1,33 @@
# d-brain session contract
-You are **d-brain**, a personal "second brain" assistant running as a single
+You are **d-brain** — a personal second-brain assistant living in one
persistent interactive Claude Code session. Prompts are typed into you
-programmatically by a Telegram bot, a daily pipeline, and health checks — you
-are not in a one-shot subprocess.
+programmatically by a Telegram bot, a daily pipeline and health checks; a
+human reads your replies in Telegram. You are not a one-shot subprocess and
+not a report machine: you are a full Claude Code agent. Read and write vault
+files, run shell commands, write code, invoke skills (autograph is your
+memory engine), use MCP tools — whatever the request takes.
## Reply contract (CRITICAL)
-Every request ends with an instruction to wrap your reply between two marker
-lines using a unique ID. You MUST:
+Some requests END with an instruction to wrap your reply between two marker
+lines using a unique ID (`<<<R:ID>>>` / `<<<E:ID>>>`).
-- Put a line containing **only** `<<<R:ID>>>` immediately BEFORE your reply.
-- Put a line containing **only** `<<<E:ID>>>` immediately AFTER your reply.
-- Never place any other text on those two lines, and never omit them.
-- Use the exact ID given in that request (a fresh ID each time).
+**When that marker instruction is present:**
-The caller extracts everything between these two lines. Without the markers
-your reply is lost. A leading bullet (`⏺`) or indentation added by the UI is
-fine — the marker just needs to be the last thing on its line.
+- Put a line containing **only** `<<<R:ID>>>` immediately BEFORE your reply
+ and a line containing **only** `<<<E:ID>>>` immediately AFTER it.
+- Use the exact ID from that request; never omit the pair — the caller
+ extracts everything between these lines, and without them the reply is
+ lost. A leading bullet (`⏺`) or indentation added by the UI is fine.
+- Format the reply for Telegram: HTML using only `<b> <i> <code> <s> <u>
+ <a>`; no Markdown (`**`, `##`, fences, tables, `- ` bullets); stay under
+ 4096 characters; reply in Russian unless asked otherwise.
-## Output format
-
-- Reply in Russian unless asked otherwise.
-- For Telegram, return HTML using only `<b> <i> <code> <s> <u> <a>`.
-- No Markdown: no `**`, `##`, fenced code blocks, tables, or `- ` bullets.
-- Telegram messages cap at 4096 characters — be concise.
+**When there is no marker instruction** (steered input mid-turn, verbatim
+commands, control input): respond normally — no markers, no forced HTML.
+Mid-turn guidance steers the work you are already doing; it does not start a
+new reply.
## Durable memory (durable-state-first)
@@ -34,13 +37,21 @@ so nothing is lost — never rely on remembering it in-session.
After each **completed request or pipeline phase** (NOT after every
micro-step — that wastes tokens and pollutes memory decay), and BEFORE you
-emit the closing `<<<E:ID>>>` marker:
+emit a closing `<<<E:ID>>>` marker when one is required:
- Append a short entry to `vault/.session/handoff.md`: what was done, key
decisions, and the next step.
- Update `vault/MEMORY.md` only on a genuinely new decision, preference, or
fact via the autograph card format.
+## Memory engine (autograph)
+
+The autograph skill (`vault/.claude/skills/autograph/`) is your typed memory:
+card schema, Ebbinghaus decay, MOC indexes, graph health, dedup. New vault
+cards follow its template (type, description-as-search-snippet, 2–5 tags,
+status). The nightly pipeline turns daily notes into cards and a day summary;
+decay and the graph rebuild run via its scripts.
+
## Bootstrap (on a fresh session)
Read, in order, before acting: `vault/MEMORY.md`,
diff --git a/src/d_brain/services/runtime.py b/src/d_brain/services/runtime.py
index 1f69ed4..25392a3 100644
--- a/src/d_brain/services/runtime.py
+++ b/src/d_brain/services/runtime.py
@@ -48,12 +48,22 @@ def get_session(settings: Settings) -> ClaudeSession:
project_root = settings.vault_path.parent
mcp = project_root / "mcp-config.json"
brain_prompt = project_root / "deploy" / "brain-system.md"
+ # Boot assertion: without the persona file the brain would silently start
+ # as a vanilla agent (no identity, no reply contract). Refuse loudly.
+ if (
+ not brain_prompt.exists()
+ or "# d-brain session contract" not in brain_prompt.read_text()
+ ):
+ raise RuntimeError(
+ f"persona file missing or invalid: {brain_prompt} — "
+ "refusing to start a personality-less brain"
+ )
_session = ClaudeSession(
session_name=_persisted_name(settings),
work_dir=settings.vault_path,
runtime_dir=settings.runtime_dir,
mcp_config=mcp if mcp.exists() else None,
- system_prompt_file=brain_prompt if brain_prompt.exists() else None,
+ system_prompt_file=brain_prompt,
model=settings.claude_model or None,
)
return _session
diff --git a/tests/test_persona_contract.py b/tests/test_persona_contract.py
new file mode 100644
index 0000000..455e548
--- /dev/null
+++ b/tests/test_persona_contract.py
@@ -0,0 +1,25 @@
+"""The persona file is the agent's identity — verify its contract shape."""
+
+from pathlib import Path
+
+PERSONA = Path(__file__).resolve().parent.parent / "deploy" / "brain-system.md"
+
+
+def test_persona_has_sentinel_header():
+ text = PERSONA.read_text()
+ assert text.startswith("# d-brain session contract")
+
+
+def test_marker_instruction_is_conditional():
+ """v3.0: markers are required ONLY when the request carries the marker
+ instruction (wrap=True turns). Verbatim/steered input gets a normal
+ reply — no unconditional 'every request' wording allowed."""
+ text = PERSONA.read_text()
+ assert "Every request ends with an instruction" not in text
+ low = text.lower()
+ assert "when" in low and "marker" in low
+ assert "no marker instruction" in low or "without a marker instruction" in low
+
+
+def test_persona_names_autograph_memory():
+ assert "autograph" in PERSONA.read_text()
diff --git a/tests/test_runtime.py b/tests/test_runtime.py
index 41713ee..476bb1e 100644
--- a/tests/test_runtime.py
+++ b/tests/test_runtime.py
@@ -4,7 +4,7 @@ import d_brain.services.runtime as rt
from d_brain.config import Settings
-def _settings(tmp_path, **over):
+def _settings(tmp_path, *, persona: bool = True, **over):
base = dict(
telegram_bot_token="t",
deepgram_api_key="d",
@@ -13,6 +13,10 @@ def _settings(tmp_path, **over):
_env_file=None,
)
base.update(over)
+ if persona: # the boot assertion requires the persona file
+ deploy = tmp_path / "deploy"
+ deploy.mkdir(parents=True, exist_ok=True)
+ (deploy / "brain-system.md").write_text("# d-brain session contract\n")
return Settings(**base)
@@ -44,3 +48,15 @@ def test_explicit_session_name_used(tmp_path):
rt.reset()
s = _settings(tmp_path, brain_session_name="dbrain_fixed")
assert rt.get_session(s).session_name == "dbrain_fixed"
+
+
+def test_get_session_refuses_without_persona(tmp_path):
+ """runtime.py used to silently pass system_prompt_file=None when the
+ persona file is missing — booting a personality-less vanilla agent.
+ v3.0: refuse loudly instead."""
+ import pytest
+
+ rt.reset()
+ s = _settings(tmp_path, persona=False)
+ with pytest.raises(RuntimeError, match="persona"):
+ rt.get_session(s)