Skip to content

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.

TypeScript

feat: add agentName to install workflow for daily log entries (v0.6.0)

Sol Aitken6be64bdb0861
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index aa4ec82f..77cbe812 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.5.5",
+ "version": "0.6.0",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": "Open Second Brain contributors",
"license": "MIT",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 201fa614..51cdde13 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.5.5",
+ "version": "0.6.0",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"keywords": ["second-brain", "obsidian", "agents", "skills", "event-log", "mcp"]
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c14f8cff..5be2ca0e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+## [0.6.0] - 2026-05-08
+
+### Added
+
+- Daily-log agent identity workflow. Each runtime install now selects an
+ agent name (e.g. `openclaw-main`, `hermes-vps-agent`, `<hostname>-codex`,
+ …) that is used as the `@agent-name` prefix in `Daily/*.md` event log
+ entries.
+- `o2b init --agent-name <name>` writes the chosen identity into
+ `AI Wiki/identity/agents.md` and replaces the template placeholder
+ (`(add your agents here, …)`). Existing vaults are upgraded in place
+ without `--force`: the placeholder line is rewritten.
+- `agentName` field in `openclaw.plugin.json` `configSchema` and `uiHints`
+ alongside `vault` / `instanceName`. The OpenClaw native plugin reads
+ `api.pluginConfig.agentName` and uses it as the default agent for
+ `event_log_append` calls that omit the `agent` argument.
+- `event_log_append` (Python MCP) now resolves the default agent from
+ `VAULT_AGENT_NAME`, then from `agent_name` / `agentName` in the
+ discovered config file, then falls back to `agent`.
+- New "Verification β€” daily identity" step in `install.md` and
+ `after-install.md`. Calls `event_log_append` without an explicit
+ `agent` and asserts the daily entry shows `@<chosen-agent-name>` rather
+ than `@agent`.
+- `install.md` now covers all four runtimes (Hermes, OpenClaw, Codex,
+ Claude Code) with runtime-appropriate agent name defaults.
+- Installation readiness criteria now require `agentName` to be configured
+ (or `VAULT_AGENT_NAME` exported), the placeholder removed from
+ `agents.md`, and the daily-identity check to pass.
+
+### Changed
+
+- Bumped package, plugin, MCP server, OpenClaw plugin, and Hermes adapter
+ versions to 0.6.0.
+
## [0.5.5] - 2026-05-08
### Added
@@ -222,7 +256,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
-[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.5.2...HEAD
+[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/itechmeat/open-second-brain/compare/v0.5.5...v0.6.0
+[0.5.5]: https://github.com/itechmeat/open-second-brain/compare/v0.5.4...v0.5.5
[0.5.2]: https://github.com/itechmeat/open-second-brain/compare/v0.5.1...v0.5.2
[0.5.1]: https://github.com/itechmeat/open-second-brain/compare/v0.5.0...v0.5.1
[0.5.0]: https://github.com/itechmeat/open-second-brain/compare/v0.4.2...v0.5.0
diff --git a/README.md b/README.md
index adb44087..4865feee 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,7 @@ OpenClaw supports this project through the **Native plugin format**: a root `pac
Install from Git:
```bash
-openclaw plugins install git:github.com/itechmeat/[email protected]
+openclaw plugins install git:github.com/itechmeat/[email protected]
```
Or from a local checkout:
@@ -75,21 +75,28 @@ Or from a local checkout:
openclaw plugins install ./open-second-brain
```
-After installing, configure the vault path:
+After installing, configure the vault path, instance name, and agent identity:
```bash
openclaw config set plugins.entries.open-second-brain.config.vault '"/path/to/vault"'
openclaw config set plugins.entries.open-second-brain.config.instanceName '"My Second Brain"'
+openclaw config set plugins.entries.open-second-brain.config.agentName '"openclaw-main"'
```
+`agentName` is the identity used in `Daily/*.md` event log entries
+(`- HH:MM β€” @openclaw-main β€” message`). Pick a name that makes the host
+or runtime obvious β€” `openclaw-main`, `openclaw-server`,
+`<hostname>-openclaw`, etc.
+
Tools are registered natively by the JS plugin entry β€” no MCP registration is needed. The five tools (`second_brain_status`, `second_brain_query`, `second_brain_capture`, `event_log_append`, `vault_health`) are available immediately after install and gateway restart. The optional MCP server (`o2b mcp`) can still be enabled for runtimes that prefer the MCP protocol.
## First run
-Create or update the OpenSecondBrain profile inside a vault:
+Create or update the OpenSecondBrain profile inside a vault. Pass
+`--agent-name` to register the identity used in Daily event log entries:
```bash
-scripts/o2b init --vault /path/to/vault --name "My Second Brain"
+scripts/o2b init --vault /path/to/vault --name "My Second Brain" --agent-name "openclaw-main"
```
Check that the vault and runtime adapters are healthy:
diff --git a/after-install.md b/after-install.md
index bc3b4193..1c98a84e 100644
--- a/after-install.md
+++ b/after-install.md
@@ -17,19 +17,33 @@ the plugin checkout. The symlinks survive `hermes plugins update` because they
point into the git-managed checkout. After this step, `o2b` and `vault-log`
will be available as bare commands.
-## 2. Initialise a vault
+## 2. Choose a Daily log agent name
+
+Pick the identity used in `Daily/*.md` for event log entries. Suggested
+defaults (any can be replaced with a custom string):
+
+- `hermes-main`, `hermes-vps-agent`, `hermes-server`
+- `<hostname>-hermes` (substitute the real hostname)
+- `second-brain-agent`
+
+The chosen name appears in daily notes as
+`- HH:MM β€” @agent-name β€” event message`. Pass it as `--agent-name` to
+`o2b init` in the next step so it is written into
+`AI Wiki/identity/agents.md` and replaces the template placeholder.
+
+## 3. Initialise a vault
Pick (or create) the Obsidian-compatible folder you want as your second
brain, then bootstrap the agent-owned files:
```bash
-o2b init --vault /path/to/vault --name "My Second Brain"
+o2b init --vault /path/to/vault --name "My Second Brain" --agent-name "<chosen-agent-name>"
o2b doctor --vault /path/to/vault --repo .
```
`o2b doctor` should print `[OK]` for every check.
-## 3. Register the MCP server (optional but recommended)
+## 4. Register the MCP server (optional but recommended)
Open Second Brain ships an optional stdio MCP server. Register it with
Hermes so the deterministic tools are routable:
@@ -46,10 +60,34 @@ quoted shell string, and do not repeat `--args` per token β€” both forms make
Hermes pass a single concatenated argument to the MCP server. Edit
`~/.hermes/config.yaml` instead if you prefer YAML.
+Set `VAULT_AGENT_NAME=<chosen-agent-name>` in the environment that
+launches the MCP server so `event_log_append` defaults to the chosen
+name when called without an explicit `agent` argument.
+
The CLI works on its own; the MCP server is opt-in. See `docs/mcp.md` for
tool schemas, per-tool arguments, and Claude Code / Codex notes.
-## 4. Updating
+## 5. Verify the daily log identity
+
+After registering the MCP server, run the **daily identity** check before
+declaring the install complete:
+
+1. Call `event_log_append` **without** an explicit `agent` argument:
+
+ ```bash
+ o2b tool-call event_log_append --vault /path/to/vault \
+ --tool-arg message="install verification"
+ ```
+
+2. Open `/path/to/vault/Daily/YYYY.MM.DD.md` and confirm the newest entry
+ shows `@<chosen-agent-name>`, **not** the `@agent` placeholder.
+3. If `@agent` appears instead, the install is **incomplete**: the
+ runtime did not pick up the agent name. Re-check that
+ `VAULT_AGENT_NAME` is exported (Hermes / Codex / Claude) or that
+ `plugins.entries.open-second-brain.config.agentName` is set
+ (OpenClaw).
+
+## 6. Updating
```bash
hermes plugins update open-second-brain
@@ -61,7 +99,7 @@ MCP registration in `~/.hermes/config.yaml` is preserved across updates.
The CLI symlinks do not need to be recreated β€” they point into the same
checkout that gets updated.
-## 5. Uninstalling
+## 7. Uninstalling
Run a dry-run first to see exactly what will happen and which Hermes
commands you need to run:
@@ -108,13 +146,19 @@ The `package.json` at the project root declares `openclaw.extensions` pointing
to the JS entry. The `openclaw.plugin.json` manifest provides static discovery
metadata (plugin ID, configuration schema, declared tool names).
-To configure the vault path:
+To configure the vault path, instance name, and agent identity:
```bash
openclaw config set plugins.entries.open-second-brain.config.vault '"/path/to/vault"'
openclaw config set plugins.entries.open-second-brain.config.instanceName '"My Second Brain"'
+openclaw config set plugins.entries.open-second-brain.config.agentName '"<chosen-agent-name>"'
```
+`agentName` is a separate field from `instanceName`. The plugin reads it
+when `event_log_append` is called without an explicit `agent` argument
+and writes entries to `Daily/*.md` as
+`- HH:MM β€” @<agentName> β€” event message`.
+
Run the doctor to verify the OpenClaw manifest and packaging are valid:
```bash
diff --git a/docs/architecture.md b/docs/architecture.md
index 5cf7f557..af836f76 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -106,7 +106,7 @@ The Python CLI (`o2b`) and MCP server (`o2b mcp`) remain available for Hermes an
Installation:
```bash
-openclaw plugins install git:github.com/itechmeat/[email protected]
+openclaw plugins install git:github.com/itechmeat/[email protected]
```
The OpenClaw adapter must remain compatible with the Hermes, Claude Code, and Codex adapters. The `o2b mcp` MCP server is still available for runtimes that prefer the MCP protocol.
diff --git a/install.md b/install.md
index fa23d5d8..9f561cf6 100644
--- a/install.md
+++ b/install.md
@@ -1,9 +1,9 @@
# open-second-brain β€” Agent Installation Guide
-> **Version 0.5.5**
+> **Version 0.6.0**
> Repository: https://github.com/itechmeat/open-second-brain
-This guide is written for an **AI agent**, not a human. It contains the exact commands and decision logic needed to install and configure the **open-second-brain** plugin autonomously. Follow exactly one of the two branches below based on the target runtime (Hermes or OpenClaw). Complete every step in the chosen branch.
+This guide is written for an **AI agent**, not a human. It contains the exact commands and decision logic needed to install and configure the **open-second-brain** plugin autonomously. Follow exactly one of the branches below based on the target runtime (Hermes, OpenClaw, Codex, or Claude). Complete every step in the chosen branch.
If at any point you are missing information β€” for example, the vault path is unknown, a required tool is not installed, or the runtime version is unclear β€” stop and ask the user for clarification. Offer concrete options where possible (e.g. suggest a default vault path, list supported Python versions, or propose an alternative runtime).
@@ -41,30 +41,66 @@ This creates symlinks in `~/.local/bin` pointing to `scripts/o2b` and `scripts/v
After this step, the bare commands `o2b` and `vault-log` will be available on PATH.
-### 3. Initialize the vault
+### 3. Choose Daily log agent name
-Replace `/path/to/vault` with the actual vault path.
+Ask the user to choose the agent name used in Daily event log entries.
+Offer these defaults plus a custom value:
+
+- `hermes-main`
+- `hermes-vps-agent`
+- `hermes-server`
+- `second-brain-agent`
+- `<hostname>-hermes`
+
+Resolve `<hostname>` from `hostname` on the target system before showing the
+list (e.g. `vps-techmeat-hermes`).
+
+Explain that this name appears in `Daily/*.md` as
+
+```
+- HH:MM β€” @agent-name β€” event message
+```
+
+Do not continue until the value is known. Pass it as `--agent-name` to
+`o2b init` in the next step.
+
+### 4. Initialize the vault
+
+Replace `/path/to/vault` and `<chosen-agent-name>` with the actual values.
```bash
-o2b init --vault /path/to/vault --name "My Second Brain"
+o2b init --vault /path/to/vault --name "My Second Brain" --agent-name "<chosen-agent-name>"
```
-### 4. Register the MCP server
+`--agent-name` writes the chosen name into `AI Wiki/identity/agents.md` and
+removes the template placeholder.
+
+### 5. Register the MCP server
```bash
hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault
hermes gateway restart
```
-### 5. Verify the installation
+Set the agent name in the environment passed to the MCP server so
+`event_log_append` can default to it when no explicit `agent` argument is
+given. The simplest way is to add `VAULT_AGENT_NAME=<chosen-agent-name>` to
+the gateway environment (or to the MCP server entry in
+`~/.hermes/config.yaml`).
+
+### 6. Verify the installation
```bash
o2b doctor --vault /path/to/vault --repo .
```
-All checks must pass. If any check fails, report the failure output to the user before continuing.
+All checks must pass. If any check fails, report the failure output to the
+user before continuing.
-### 6. Update
+Then run the **daily identity** check (see Β§ Verification β€” daily identity
+below). Installation is incomplete until that check passes.
+
+### 7. Update
```bash
hermes plugins update open-second-brain
@@ -74,7 +110,7 @@ o2b doctor --vault /path/to/vault --repo .
The CLI symlinks created in step 2 do not need to be recreated after an update β€” they point into the git checkout, which `hermes plugins update` refreshes via `git pull`.
-### 7. Uninstall
+### 8. Uninstall
Run in this order:
@@ -100,7 +136,7 @@ The vault and its Markdown files are never deleted by the uninstall process.
From Git (pin to a version tag):
```bash
-openclaw plugins install git:github.com/itechmeat/[email protected]
+openclaw plugins install git:github.com/itechmeat/[email protected]
```
Or from a local checkout:
@@ -127,33 +163,79 @@ install. Run this step to create symlinks:
This creates symlinks in `~/.local/bin`. After this, bare `o2b` and
`vault-log` work on PATH.
-### 3. Initialize the vault
+### 3. Choose Daily log agent name
+
+Ask the user to choose the agent name used in Daily event log entries.
+Offer these defaults plus a custom value:
-Replace `/path/to/vault` with the actual vault path.
+- `openclaw-main`
+- `openclaw-server`
+- `server-agent`
+- `second-brain-agent`
+- `<hostname>-openclaw`
+
+Resolve `<hostname>` from `hostname` on the target system before showing the
+list (e.g. `vps-techmeat-openclaw`).
+
+Explain that this name appears in `Daily/*.md` as
+
+```
+- HH:MM β€” @agent-name β€” event message
+```
+
+Do not continue until the value is known. The chosen name is stored in the
+plugin config in step 5 as `agentName` and is written into
+`AI Wiki/identity/agents.md` by `o2b init` in step 4.
+
+### 4. Initialize the vault
+
+Replace `/path/to/vault` and `<chosen-agent-name>` with the actual values.
```bash
-o2b init --vault /path/to/vault --name "My Second Brain"
+o2b init --vault /path/to/vault --name "My Second Brain" --agent-name "<chosen-agent-name>"
```
-### 4. Configure the vault path
+### 5. Configure the vault path and agent name
-Tools are registered natively by the JS plugin entry β€” no MCP registration is needed. Set the vault path in the OpenClaw plugin config:
+Tools are registered natively by the JS plugin entry β€” no MCP registration
+is needed. Set the vault path, instance name, and agent name in the
+OpenClaw plugin config:
```bash
openclaw config set plugins.entries.open-second-brain.config.vault '"/path/to/vault"'
openclaw config set plugins.entries.open-second-brain.config.instanceName '"My Second Brain"'
+openclaw config set plugins.entries.open-second-brain.config.agentName '"<chosen-agent-name>"'
```
-### 5. Verify the installation
+The resulting plugin entry must contain `agentName` as a separate field
+alongside `instanceName` (do not merge the two):
+
+```json
+{
+ "enabled": true,
+ "config": {
+ "vault": "/path/to/vault",
+ "instanceName": "My Second Brain",
+ "agentName": "<chosen-agent-name>",
+ "mcpEnabled": false
+ }
+}
+```
+
+### 6. Verify the installation
```bash
o2b doctor --vault /path/to/vault --repo .
openclaw plugins inspect open-second-brain --runtime --json
```
-Both commands must succeed. If any check fails, report the failure output to the user before continuing.
+Both commands must succeed. If any check fails, report the failure output
+to the user before continuing.
-### 6. Update
+Then run the **daily identity** check (see Β§ Verification β€” daily identity
+below). Installation is incomplete until that check passes.
+
+### 7. Update
```bash
openclaw plugins update open-second-brain
@@ -163,7 +245,7 @@ o2b doctor --vault /path/to/vault --repo .
The CLI symlinks created in step 2 do not need to be recreated after an update.
-### 7. Uninstall
+### 8. Uninstall
```bash
openclaw plugins uninstall open-second-brain
@@ -177,3 +259,236 @@ o2b uninstall --apply-local --remove-cli
```
The vault and its Markdown files are never deleted by the uninstall process.
+
+---
+
+## Branch C β€” Codex
+
+### 1. Install the plugin
+
+Codex consumes the bundled `.codex-plugin/plugin.json` manifest. Install
+the plugin from Git through the Codex CLI:
+
+```bash
+codex plugins install git:github.com/itechmeat/[email protected]
+```
+
+### 2. Publish CLI commands to PATH
+
+```bash
+./scripts/o2b install-cli
+```
+
+### 3. Choose Daily log agent name
+
+Ask the user to choose the agent name used in Daily event log entries.
+Offer these defaults plus a custom value:
+
+- `codex-main`
+- `codex-vps-agent`
+- `codex-server`
+- `second-brain-agent`
+- `<hostname>-codex`
+
+Resolve `<hostname>` from `hostname` on the target system before showing
+the list. Explain that this name appears in `Daily/*.md` as
+`- HH:MM β€” @agent-name β€” event message`. Do not continue until the value
+is known.
+
+### 4. Initialize the vault
+
+```bash
+o2b init --vault /path/to/vault --name "My Second Brain" --agent-name "<chosen-agent-name>"
+```
+
+### 5. Wire up the agent name for the Codex runtime
+
+Codex consumes Open Second Brain through the optional MCP stdio server.
+Export `VAULT_AGENT_NAME=<chosen-agent-name>` in the environment that
+launches the MCP server so `event_log_append` defaults to that name when
+called without an explicit `agent` argument.
+
+A minimal Codex `mcp_servers` entry:
+
+```yaml
+mcp_servers:
+ open-second-brain:
+ command: o2b
+ args: ["mcp", "--vault", "/path/to/vault"]
+ env:
+ VAULT_AGENT_NAME: "<chosen-agent-name>"
+```
+
+### 6. Verify the installation
+
+```bash
+o2b doctor --vault /path/to/vault --repo .
+```
+
+Then run the **daily identity** check (see Β§ Verification β€” daily identity
+below). Installation is incomplete until that check passes.
+
+### 7. Update
+
+```bash
+codex plugins update open-second-brain
+```
+
+The CLI symlinks created in step 2 do not need to be recreated after an
+update β€” they point into the git checkout, which the plugin updater
+refreshes.
+
+### 8. Uninstall
+
+```bash
+codex plugins uninstall open-second-brain
+o2b uninstall --apply-local --remove-cli
+```
+
+The vault and its Markdown files are never deleted by the uninstall process.
+
+---
+
+## Branch D β€” Claude Code
+
+### 1. Install the plugin
+
+Claude Code consumes the bundled `.claude-plugin/plugin.json` manifest.
+Install the plugin from Git:
+
+```bash
+claude plugins install git:github.com/itechmeat/[email protected]
+```
+
+### 2. Publish CLI commands to PATH
+
+```bash
+./scripts/o2b install-cli
+```
+
+### 3. Choose Daily log agent name
+
+Ask the user to choose the agent name used in Daily event log entries.
+Offer these defaults plus a custom value:
+
+- `claude-main`
+- `claude-vps-agent`
+- `claude-server`
+- `second-brain-agent`
+- `<hostname>-claude`
+
+Resolve `<hostname>` from `hostname` on the target system before showing
+the list. Explain that this name appears in `Daily/*.md` as
+`- HH:MM β€” @agent-name β€” event message`. Do not continue until the value
+is known.
+
+### 4. Initialize the vault
+
+```bash
+o2b init --vault /path/to/vault --name "My Second Brain" --agent-name "<chosen-agent-name>"
+```
+
+### 5. Wire up the agent name for the Claude runtime
+
+Claude Code talks to Open Second Brain over the optional MCP stdio server.
+Export `VAULT_AGENT_NAME=<chosen-agent-name>` in the environment that
+launches the MCP server so `event_log_append` defaults to that name when
+called without an explicit `agent` argument.
+
+A minimal Claude Code `mcp_servers` entry:
+
+```yaml
+mcp_servers:
+ open-second-brain:
+ command: o2b
+ args: ["mcp", "--vault", "/path/to/vault"]
+ env:
+ VAULT_AGENT_NAME: "<chosen-agent-name>"
+```
+
+### 6. Verify the installation
+
+```bash
+o2b doctor --vault /path/to/vault --repo .
+```
+
+Then run the **daily identity** check (see Β§ Verification β€” daily identity
+below). Installation is incomplete until that check passes.
+
+### 7. Update
+
+```bash
+claude plugins update open-second-brain
+```
+
+The CLI symlinks created in step 2 do not need to be recreated after an
+update β€” they point into the git checkout, which the plugin updater
+refreshes.
+
+### 8. Uninstall
+
+```bash
+claude plugins uninstall open-second-brain
+o2b uninstall --apply-local --remove-cli
+```
+
+The vault and its Markdown files are never deleted by the uninstall process.
+
+---
+
+## Verification β€” daily identity
+
+`o2b doctor` and `vault_health` confirm that the vault is structurally
+valid, but they do not verify that the agent will write under the chosen
+identity. Run this extra check after every install:
+
+1. Call `event_log_append` **without** an explicit `agent` argument.
+ Through the MCP server:
+
+ ```bash
+ o2b tool-call event_log_append --vault /path/to/vault \
+ --tool-arg message="install verification"
+ ```
+
+2. Open the daily note that was just written:
+
+ ```
+ /path/to/vault/Daily/YYYY.MM.DD.md
+ ```
+
+3. The newest entry must show `@<chosen-agent-name>`, **not** the
+ `@agent` placeholder. Example:
+
+ ```
+ - 14:32 β€” @openclaw-main β€” install verification
+ ```
+
+4. If `@agent` appears instead, stop and report the install as
+ **incomplete**: the runtime did not pick up the configured `agentName`.
+ Re-check step 5 of the chosen branch (plugin config or MCP env).
+
+---
+
+## Installation readiness criteria
+
+The installation is complete **only** when **all** of the following hold:
+
+- [ ] plugin installed;
+- [ ] gateway restarted;
+- [ ] plugin runtime status is `loaded`;
+- [ ] all tools registered;
+- [ ] vault initialized (`o2b init` succeeded);
+- [ ] `vault_health` (or `o2b doctor`) reports OK;
+- [ ] for OpenClaw: `plugins.entries.open-second-brain.config.agentName` is
+ set to the chosen name;
+- [ ] for Hermes / Codex / Claude: `VAULT_AGENT_NAME` is exported in the
+ environment that launches the MCP server;
+- [ ] `AI Wiki/identity/agents.md` contains the chosen agent name and no
+ longer contains the `(add your agents here, …)` template
+ placeholder;
+- [ ] `event_log_append` called **without** an explicit `agent` argument
+ writes a `Daily/*.md` entry under the chosen name (see Verification
+ β€” daily identity above), not under `@agent`.
+
+If any single item is missing, the install is **incomplete** β€” report
+that to the user and do not mark the workflow as successful.
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 783a91e5..40b230e1 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "0.5.5",
+ "version": "0.6.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
@@ -26,6 +26,10 @@
"type": "string",
"description": "Human-readable name for this second brain instance."
},
+ "agentName": {
+ "type": "string",
+ "description": "Identity used in Daily/*.md event log entries (e.g. 'openclaw-main'). Falls back to VAULT_AGENT_NAME, then to '@agent'."
+ },
"mcpEnabled": {
"type": "boolean",
"default": false,
@@ -42,6 +46,10 @@
"label": "Instance Name",
"help": "Human-readable name for this second brain instance."
},
+ "agentName": {
+ "label": "Agent Name",
+ "help": "Identity used in Daily/*.md as @agent-name for event log entries."
+ },
"mcpEnabled": {
"label": "Enable MCP Server",
"help": "Expose Open Second Brain as an MCP stdio server (optional)."
diff --git a/openclaw/index.js b/openclaw/index.js
index df48bc45..53183ec1 100644
--- a/openclaw/index.js
+++ b/openclaw/index.js
@@ -36,7 +36,7 @@ import { existsSync } from "node:fs";
// ── Constants ──────────────────────────────────────────────────────────────
-const PLUGIN_VERSION = "0.5.2";
+const PLUGIN_VERSION = "0.6.0";
const SECRET_KEY_PARTS = ["key", "token", "secret", "password", "credential"];
@@ -412,7 +412,13 @@ export default definePluginEntry({
throw new Error("missing required argument: message");
}
- const agent = params.agent || process.env.VAULT_AGENT_NAME || "agent";
+ const pluginConfig = api.pluginConfig || {};
+ const configuredAgent = pluginConfig.agentName || null;
+ const agent =
+ params.agent ||
+ process.env.VAULT_AGENT_NAME ||
+ configuredAgent ||
+ "agent";
const date = params.date || null;
const time = params.time || null;
diff --git a/package.json b/package.json
index 49ad460d..114420c4 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.5.5",
+ "version": "0.6.0",
"type": "module",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
diff --git a/plugin.yaml b/plugin.yaml
index 4c6e25d4..440255dd 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.5.5"
+version: "0.6.0"
description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index a3718b6c..a3123451 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.5.4"
+version: "0.6.0"
description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/pyproject.toml b/pyproject.toml
index e219b0d3..14624cb5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "open-second-brain"
-version = "0.5.5"
+version = "0.6.0"
description = "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/src/open_second_brain/__init__.py b/src/open_second_brain/__init__.py
index c425b44a..3b943d38 100644
--- a/src/open_second_brain/__init__.py
+++ b/src/open_second_brain/__init__.py
@@ -1,3 +1,3 @@
"""Open Second Brain core package."""
-__version__ = "0.5.4"
+__version__ = "0.6.0"
diff --git a/src/open_second_brain/cli.py b/src/open_second_brain/cli.py
index 1a74fc62..18d02cf6 100644
--- a/src/open_second_brain/cli.py
+++ b/src/open_second_brain/cli.py
@@ -35,6 +35,16 @@ def build_parser() -> argparse.ArgumentParser:
init_cmd = subcommands.add_parser("init", help="Initialize a vault profile with required files")
init_cmd.add_argument("--vault", type=Path, required=True, help="Vault directory path")
init_cmd.add_argument("--name", default="Second Brain", help="Instance name (default: Second Brain)")
+ init_cmd.add_argument(
+ "--agent-name",
+ dest="agent_name",
+ default=None,
+ help=(
+ "Agent identity used in Daily event log entries (e.g. 'openclaw-main'). "
+ "When set, the chosen name is written into AI Wiki/identity/agents.md "
+ "and replaces the @agent placeholder in subsequent event_log_append calls."
+ ),
+ )
init_cmd.add_argument("--force", action="store_true", help="Overwrite existing files")
doctor_cmd = subcommands.add_parser("doctor", help="Run health checks on vault, config, and plugins")
@@ -159,8 +169,14 @@ def command_status(args: argparse.Namespace) -> int:
def command_init(args: argparse.Namespace) -> int:
vault = args.vault
+ agent_name = getattr(args, "agent_name", None)
try:
- created = bootstrap_vault(vault, name=args.name, force=args.force)
+ created = bootstrap_vault(
+ vault,
+ name=args.name,
+ agent_name=agent_name,
+ force=args.force,
+ )
except OSError as exc:
print(f"error: failed to initialize vault: {exc}", file=sys.stderr)
return 1
@@ -171,6 +187,8 @@ def command_init(args: argparse.Namespace) -> int:
print(f"initialized vault: {vault}")
for path in created:
print(f" created: {path}")
+ if agent_name:
+ print(f"agent name registered: {agent_name}")
return 0
diff --git a/src/open_second_brain/init.py b/src/open_second_brain/init.py
index 4e014293..a3b6050b 100644
--- a/src/open_second_brain/init.py
+++ b/src/open_second_brain/init.py
@@ -67,31 +67,64 @@ TEMPLATES: dict[Path, str] = {
"# Agent Identity\n\n"
"Allowed agents and their scopes.\n\n"
"## Registered agents\n\n"
- "- (add your agents here, e.g., my-agent: operator on my-server)\n\n"
+ "{agents_block}\n\n"
"## Scopes\n\n"
"- Write scope: AI Wiki/, Daily/\n"
"- Read scope: whole vault\n"
),
}
+AGENTS_PLACEHOLDER = "- (add your agents here, e.g., my-agent: operator on my-server)"
+
+
+def _agents_block(agent_name: str | None) -> str:
+ if agent_name:
+ return f"- {agent_name}: primary agent on this server"
+ return AGENTS_PLACEHOLDER
+
def bootstrap_vault(
vault_dir: Path,
*,
name: str = "Second Brain",
+ agent_name: str | None = None,
force: bool = False,
) -> list[Path]:
created: list[Path] = []
now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+ agents_block = _agents_block(agent_name)
for rel_path in VAULT_FILES:
target = vault_dir / rel_path
target.parent.mkdir(parents=True, exist_ok=True)
if target.exists() and not force:
+ if rel_path == Path("AI Wiki") / "identity" / "agents.md" and agent_name:
+ upgraded = _upgrade_agents_file(target, agent_name)
+ if upgraded:
+ created.append(rel_path)
continue
template = TEMPLATES.get(rel_path, "")
- content = template.format(name=name, created=now)
+ content = template.format(name=name, created=now, agents_block=agents_block)
target.write_text(content, encoding="utf-8")
created.append(rel_path)
return created
+
+
+def _upgrade_agents_file(path: Path, agent_name: str) -> bool:
+ """Replace the template placeholder with the chosen agent entry.
+
+ Returns True if the file was rewritten.
+ """
+ try:
+ text = path.read_text(encoding="utf-8")
+ except OSError:
+ return False
+ entry = f"- {agent_name}: primary agent on this server"
+ if entry in text:
+ return False
+ if AGENTS_PLACEHOLDER in text:
+ new_text = text.replace(AGENTS_PLACEHOLDER, entry)
+ path.write_text(new_text, encoding="utf-8")
+ return True
+ return False
diff --git a/src/open_second_brain/mcp.py b/src/open_second_brain/mcp.py
index 4eed5f2d..38d8f2fc 100644
--- a/src/open_second_brain/mcp.py
+++ b/src/open_second_brain/mcp.py
@@ -29,7 +29,7 @@ from open_second_brain.vault import list_vault_pages, parse_frontmatter, write_f
PROTOCOL_VERSION = "2025-06-18"
SERVER_NAME = "open-second-brain"
-SERVER_VERSION = "0.5.4"
+SERVER_VERSION = "0.6.0"
JSONRPC_VERSION = "2.0"
# JSON-RPC 2.0 error codes used by the MCP server.
@@ -354,14 +354,20 @@ def _tool_second_brain_capture(server: MCPServer, arguments: dict[str, Any]) ->
}
+def _resolve_default_agent(server: MCPServer) -> str:
+ env_value = os.environ.get("VAULT_AGENT_NAME")
+ if env_value:
+ return env_value
+ discovery = discover_config(server.config_path)
+ config_value = discovery.data.get("agent_name") or discovery.data.get("agentName")
+ if config_value:
+ return config_value
+ return "agent"
+
+
def _tool_event_log_append(server: MCPServer, arguments: dict[str, Any]) -> dict[str, Any]:
message = _coerce_str(arguments, "message")
- agent = _coerce_str(
- arguments,
- "agent",
- required=False,
- default=os.environ.get("VAULT_AGENT_NAME", "agent"),
- )
+ agent = _coerce_str(arguments, "agent", required=False)
date = _coerce_str(arguments, "date", required=False)
time = _coerce_str(arguments, "time", required=False)
assert message is not None # required=True
@@ -369,7 +375,7 @@ def _tool_event_log_append(server: MCPServer, arguments: dict[str, Any]) -> dict
if time is not None:
validate_event_time(time)
- effective_agent = agent or "agent"
+ effective_agent = agent or _resolve_default_agent(server)
path = append_event(server.vault, effective_agent, message, date=date, time=time)
return {
diff --git a/tests/test_cli.py b/tests/test_cli.py
index 1632e1f5..34a99c4a 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -47,6 +47,26 @@ class CliTests(unittest.TestCase):
self.assertTrue((vault / "AI Wiki" / "_OPEN_SECOND_BRAIN.md").is_file())
self.assertTrue((vault / "AI Wiki" / "identity" / "agents.md").is_file())
+ def test_init_with_agent_name_writes_identity_entry(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ result = run_cli(
+ "init",
+ "--vault",
+ str(vault),
+ "--name",
+ "Test",
+ "--agent-name",
+ "openclaw-main",
+ )
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertIn("agent name registered: openclaw-main", result.stdout)
+ agents_md = (vault / "AI Wiki" / "identity" / "agents.md").read_text(
+ encoding="utf-8"
+ )
+ self.assertIn("- openclaw-main: primary agent on this server", agents_md)
+ self.assertNotIn("(add your agents here", agents_md)
+
def test_init_already_initialized_does_not_overwrite(self):
with tempfile.TemporaryDirectory() as tmp:
vault = Path(tmp)
diff --git a/tests/test_init.py b/tests/test_init.py
index 27c2fdc4..6ae58c2e 100644
--- a/tests/test_init.py
+++ b/tests/test_init.py
@@ -2,7 +2,7 @@ import tempfile
import unittest
from pathlib import Path
-from open_second_brain.init import bootstrap_vault, VAULT_FILES
+from open_second_brain.init import AGENTS_PLACEHOLDER, bootstrap_vault, VAULT_FILES
class InitTests(unittest.TestCase):
@@ -27,6 +27,40 @@ class InitTests(unittest.TestCase):
manual = (vault / "AI Wiki" / "_OPEN_SECOND_BRAIN.md").read_text(encoding="utf-8")
self.assertIn("Test Brain", manual)
+ def test_bootstrap_vault_writes_agent_name(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ bootstrap_vault(vault, name="Test", agent_name="openclaw-main")
+ agents_md = (vault / "AI Wiki" / "identity" / "agents.md").read_text(
+ encoding="utf-8"
+ )
+ self.assertIn("- openclaw-main: primary agent on this server", agents_md)
+ self.assertNotIn(AGENTS_PLACEHOLDER, agents_md)
+
+ def test_bootstrap_vault_without_agent_name_keeps_placeholder(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ bootstrap_vault(vault, name="Test")
+ agents_md = (vault / "AI Wiki" / "identity" / "agents.md").read_text(
+ encoding="utf-8"
+ )
+ self.assertIn(AGENTS_PLACEHOLDER, agents_md)
+
+ def test_bootstrap_vault_upgrades_existing_placeholder_in_place(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ # First init without agent name leaves placeholder.
+ bootstrap_vault(vault, name="Test")
+ agents_path = vault / "AI Wiki" / "identity" / "agents.md"
+ self.assertIn(AGENTS_PLACEHOLDER, agents_path.read_text(encoding="utf-8"))
+
+ # Second init with agent_name (no --force) must rewrite the placeholder.
+ created = bootstrap_vault(vault, name="Test", agent_name="hermes-main")
+ self.assertIn(Path("AI Wiki") / "identity" / "agents.md", created)
+ text = agents_path.read_text(encoding="utf-8")
+ self.assertIn("- hermes-main: primary agent on this server", text)
+ self.assertNotIn(AGENTS_PLACEHOLDER, text)
+
def test_bootstrap_vault_does_not_overwrite_by_default(self):
with tempfile.TemporaryDirectory() as tmp:
vault = Path(tmp)
diff --git a/tests/test_mcp.py b/tests/test_mcp.py
index c731d19e..a7ec44fc 100644
--- a/tests/test_mcp.py
+++ b/tests/test_mcp.py
@@ -253,6 +253,40 @@ class ToolCallTests(unittest.TestCase):
daily = vault / "Daily" / "2026.05.06.md"
self.assertIn("- 11:42 β€” @mcp-test β€” via mcp", daily.read_text(encoding="utf-8"))
+ def test_event_log_append_uses_config_agent_name_default(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp) / "vault"
+ vault.mkdir()
+ config = Path(tmp) / "config.yaml"
+ config.write_text("agent_name: openclaw-main\n", encoding="utf-8")
+ server = _make_server(vault, config=config)
+ _initialize(server)
+
+ # Ensure environment variable does not shadow the config default
+ prior_env = os.environ.pop("VAULT_AGENT_NAME", None)
+ try:
+ response = _call_tool(
+ server,
+ "event_log_append",
+ {
+ "message": "from-config-default",
+ "date": "2026.05.06",
+ "time": "12:00",
+ },
+ )
+ finally:
+ if prior_env is not None:
+ os.environ["VAULT_AGENT_NAME"] = prior_env
+
+ self.assertFalse(response["result"]["isError"])
+ structured = response["result"]["structuredContent"]
+ self.assertEqual(structured["agent"], "openclaw-main")
+ daily = vault / "Daily" / "2026.05.06.md"
+ self.assertIn(
+ "- 12:00 β€” @openclaw-main β€” from-config-default",
+ daily.read_text(encoding="utf-8"),
+ )
+
def test_event_log_append_rejects_invalid_time(self):
with tempfile.TemporaryDirectory() as tmp:
server = _make_server(Path(tmp))
diff --git a/tests/test_openclaw_plugin.py b/tests/test_openclaw_plugin.py
index 52f6b0c0..3d360887 100644
--- a/tests/test_openclaw_plugin.py
+++ b/tests/test_openclaw_plugin.py
@@ -34,7 +34,7 @@ class OpenClawManifestValidityTests(unittest.TestCase):
self.assertEqual(schema["type"], "object")
def test_manifest_has_version(self):
- self.assertEqual(self.manifest["version"], "0.5.4")
+ self.assertEqual(self.manifest["version"], "0.6.0")
def test_manifest_declares_tools(self):
tools = self.manifest["contracts"]["tools"]
@@ -133,7 +133,7 @@ class OpenClawPackageJsonTests(unittest.TestCase):
self.assertEqual(self.pkg["name"], "open-second-brain")
def test_package_json_has_version(self):
- self.assertEqual(self.pkg["version"], "0.5.4")
+ self.assertEqual(self.pkg["version"], "0.6.0")
def test_package_json_has_type_module(self):
self.assertEqual(self.pkg["type"], "module")