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.
Consultant prompt β release "codegraph-link-depth-mcp"
You are a senior backend architect. Propose architectural variants for ONE coherent release of the Open Second Brain project. Output variants and a recommendation only β no implementation code, nothing outside the requested sections (see "Required output format" at the end).
Project
- Name:
open-second-brain(npmopen-second-brain, CLI binaryo2b). - Language / runtime: TypeScript, ESM (
"type": "module"), executed on Bun (also Node-compatible for the CLI).package.jsonversion1.16.0. - Dependency posture: intentionally minimal. Runtime deps =
proper-lockfileonly. No HTTP framework, no MCP SDK. Optional native deps:sqlite-vec,@node-rs/jieba,tiny-segmenter. - Tooling: tests via
bash scripts/test(Bun's test runner,bun:test);oxlint(lint),oxfmt(format),tsc --noEmit(typecheck);bun run validate= typecheck + lint + test. Strict TDD convention: write the focused failing test first, then implement, then refactor. - Conventions (hard): SOLID / KISS / DRY; no misleading fallbacks (a degraded path must SAY it degraded, never report success silently); no hardcoding; all strings/identifiers English-only and language-agnostic; new behavior must be backward compatible β existing outputs stay byte-identical when no new flag/option is supplied. Keep the dependency set minimal: prefer Node/Bun built-ins over new packages.
Release theme
"CodeGraph link-graph depth + MCP exposure" β a single, coherent, forward-only release composed of exactly four in-scope tasks (do not add, drop, or substitute). Two deepen the link graph / extraction; two expose the existing MCP server through new packaging and transports.
In-scope tasks (verbatim bodies)
t_13c92d85 (priority 4 β CORE): resolve reference-style Markdown links into graph edges
Graphify turns Markdown links into graph edges: it resolves inline
[text](./other.md), reference-style links, and [[wikilinks]] relative to
the source file, skips external URLs/anchors/images, and emits references
edges so hub docs surface as graph hubs.
Status in OSB: present_weaker. extractLinks
(src/core/search/links.ts:60) already covers wikilinks (WIKILINK_ALIAS_RE),
inline markdown links (MD_LINK_RE, line 29), external-URL skip (isUrl line
40), mailto skip (isMailto line 44), image-embed exclusion (negative
lookbehind (?<!!) on MD_LINK_RE), and #anchor fragment stripping (lines
79-81). It is invoked by the indexer (indexInto β extractLinks,
src/core/search/indexer.ts) and persisted via store.replaceLinks;
hub/backlink ranking exists via buildBacklinkIndex / pickTopReferenced
(src/core/brain/backlinks.ts:98). Gap: MD_LINK_RE matches only the
inline [text](target) form β reference-style links ([text][label] /
[text][] / [text] shortcut forms plus their [label]: url definitions) are
never resolved, so LinkType (line 17) has no path for them.
Closing the gap means a reference-definition pass (collect [label]: target
lines, then match [text][label] / [text][] / [text] shortcut references
against them) feeding the same markdown_link row shape; the existing
isUrl/isMailto/anchor-strip filters apply unchanged to the resolved target.
Relative-path resolution to canonical doc ids stays the indexer's job.
t_da6321a9 (priority 3): graphify-mcp console script for stdio MCP server
Graphify v0.8.36 added a graphify-mcp console script β MCP stdio server
directly invocable from uv tool install / pipx.
Status in OSB: not_in_osb_useful. OSB has an MCP server (src/mcp/server.ts)
but it is only reachable via the o2b mcp serve CLI command or by importing the
class. src/mcp/index.ts:19 exports serveStdio, serveStdioFromString;
pyproject.toml has no console_scripts entry for MCP; package.json has no bin
entry for the MCP server. Goal: a dedicated entry point so OSB runs as an MCP
server via standard JS/Node tooling (npx, global install) without the o2b mcp
subcommand. Triage validator note: this is the packaging layer, distinct
from t_31dfae18 (transport layer).
t_31dfae18 (priority 2): streamable HTTP MCP transport with API-key auth
Graphify v0.8.34 added a Streamable HTTP MCP transport: graphify serve graph.json --transport http serves the graph over HTTP so a team shares one
server. Includes API-key auth (--api-key) and a Docker image.
Status in OSB: not_in_osb_useful. OSB's MCP server only supports stdio via
serveStdio (src/mcp/stdio.ts:22). An HTTP transport would let multiple
agents/clients connect to a shared brain, enable remote access, and support
team-wide sharing; API-key auth gives a simple security model. Triage validator
note: this is the transport layer, distinct from t_da6321a9 (packaging).
t_85252236 (priority 1): offline code-only extraction without API keys
Graphify v0.8.32 made code-only extraction work fully offline: graphify extract
defers backend resolution until after file detection β a corpus with only code
files runs without any GEMINI_API_KEY / ANTHROPIC_API_KEY. Keys are only
required when docs/PDFs/images are present.
Status in OSB: not_in_osb_useful. NOTE: the task's codegraph hint is
partly inaccurate and must be corrected by the design. Findings from the
current source:
- Session import is already fully offline.
src/core/brain/sessions/import.ts(importSession/importSessionPath) runs a deterministic pipeline (discoverMarkers,extractFacts,routeExtractedFacts,validateBrainFeedbackInput,importSessionRecall) that never calls an LLM and reads no provider credentials. So "session import requires provider credentials" is false today. - Vault indexing is already offline-capable. Lexical FTS5 indexing
(
src/core/search/indexer.ts) needs no key. The only credential-gated path is semantic embeddings:populateEmbeddingsthrowsEMBEDDING_KEY_MISSINGonly whenconfig.semantic.enabledAND provider !=localAND noapiKeyAND embeddings are actually being computed.indexStats/indexCheckalready degrade with the warning"embedding_api_key not configured; semantic search disabled". A keylesslocalembedding provider exists.
So the honest, graphify-inspired scope here is deferred, content-aware backend resolution + an explicit offline guarantee, not a brand-new extraction engine: ensure a keyless environment runs the full deterministic pipeline (lexical indexing + session import) to completion, surface any credential requirement as an explicit, deferred reason (never an up-front hard fail of the whole run), and lock the guarantee with a regression test that the keyless paths never read provider credentials.
Relevant architecture (current source)
MCP server (hand-rolled JSON-RPC 2.0, protocol 2025-06-18)
src/mcp/server.tsβMCPServerclass.handleRequest(request)dispatchesinitialize,notifications/initialized,ping,tools/list,tools/call,resources/list,resources/templates/list,resources/read. Advertisestools+resourcescapabilities. Tools built viabuildToolTable(scope); runtime capability window can narrow (never widen) the surface. Output goes throughbuildMcpToolResultwith an optional preview budget + artifact store. PubliccallTool(name, args)exists for the CLI bridge.src/mcp/stdio.tsβserveStdio(ctx, ioOpts, runtimeOpts): readline loop, newline-delimited JSON, onehandleRequestper line. Rejects batch arrays (INVALID_REQUEST, the2025-06-18spec removed batch support). AlsoserveStdioFromString(ctx, input, opts)for in-memory tests.src/mcp/index.tsβ public barrel re-exportingMCPServer,serveStdio,serveStdioFromString, protocol constants, etc.src/mcp/protocol.tsβPROTOCOL_VERSION = "2025-06-18",SERVER_NAME,SERVER_VERSION(from package.json), JSON-RPC error codes,MCPError.- CLI dispatch:
src/cli/main.tshas theo2b mcpcommand (call itcmdMcp). It parses--vault,--config,--repo,--scope full|writer|catalog,--tool-profile,--writer-only,--probe,--json,--allow-tool,--disable-tool,--max-tools; constructs the server; prints[mcp] <name> <version> listening on stdio (vault=<vault>)to stderr; then callsserveStdio. JSON-RPC frames go to stdout only; logs to stderr. package.jsonbin:o2bβ./scripts/o2b,vault-logβ./scripts/vault-log.scripts/o2bis a bash launcher that sources a bun precheck andexec bun run $REPO_ROOT/src/cli/main.ts "$@". No MCP-specific bin entry.docs/mcp.mddocuments the stdio server, Hermes/Claude Code/Codex registration, profiles, and the writer split.
Link extraction (src/core/search/links.ts) β see task t_13c92d85 above.
extractLinks(content) returns ExtractedLink[] ({ targetPath, linkText, linkType }, LinkType = "wikilink" | "markdown_link" | "tag"). Order: strip
code fences + inline code (stripCode), then wikilinks, then inline MD links,
then tags, then dedupe by type|target|text. No standalone test file for
links.ts today (covered indirectly via indexer tests) β a clean TDD target.
Indexing & credentials (src/core/search/indexer.ts) β see t_85252236
findings above. ResolvedSearchConfig.semantic has enabled, provider
(incl. keyless local), model, apiKey, costGateUsd, batchSize,
concurrency.
Constraints for this release
- Backward compatible:
o2b mcpstdio behavior andextractLinksoutput for inline links stay byte-identical when no new flag/option is supplied. - MCP stays optional; nothing in the kernel may depend on the MCP server running.
- The
2025-06-18protocol contract (no batch; JSON-RPC 2.0;initializeβnotifications/initializedβtools/list|call) is preserved on every transport. - HTTP transport must reuse
MCPServer.handleRequest(single source of truth for JSON-RPC dispatch) β do not duplicate request handling. Prefer Node/Bun built-inhttpover adding a framework dependency (KISS, minimal deps). - API-key auth on the HTTP transport: constant-time compare, reject unauthenticated requests with the correct HTTP status, never leak whether the failure is "missing" vs "wrong" beyond a single generic 401.
- No misleading fallbacks: every degraded/offline path reports its mode explicitly in its structured output.
- The four tasks ship together but are driven one card at a time on a shared
branch; each card's change must build cleanly on top of the previously-driven
cards' commits (no duplicate abstractions, no conflicts on shared files like
docs/mcp.md,docs/cli-reference.md,CHANGELOG.md).
Recent release history (git log, newest first)
da2e3cc feat: memory subsystem alignment (v1.16.0) (#107)
4db7862 fix(hermes): pass --repo so bridge skill discovery resolves repoRoot (#106)
0a4b6da feat: calendar obligations, agenda synthesis, OKF portability (v1.15.0) (#105)
f8b4abf feat(brain): add feedback default scope and vault write containment (#104)
20ea7ef feat: per-handoff LLM generation tracing and prompt-prefix stability (#102)
9c1d48f feat: CodeGraph and MCP operational readability (v1.12.0) (#101)
c2c3ff4 feat: Session Knowledge Synthesis Suite (v1.11.0) (#100)
... (older suites: recall quality, portability, indexer durability, provenance, integrity, search quality)
The directly related predecessor is 9c1d48f (CodeGraph + MCP operational
readability, v1.12.0): read-only brain_codegraph_report + option-gated cluster
batching, deliberately keeping partner integration read-only and not adding new
graph edge schemas. This release continues that posture on the MCP side while
adding the one missing link-graph edge form (reference-style links).
Required output format
Produce exactly these sections and nothing else:
Variant 1
- Approach: 2-3 sentences.
- Trade-offs: bullets.
- Complexity: small | medium | large.
- Risk: low | medium | high.
Variant 2
- Approach: 2-3 sentences.
- Trade-offs: bullets.
- Complexity: small | medium | large.
- Risk: low | medium | high.
Variant 3
- Approach: 2-3 sentences.
- Trade-offs: bullets.
- Complexity: small | medium | large.
- Risk: low | medium | high.
Recommended: Variant N
A short rationale (a few sentences) naming the concrete reasons the chosen variant fits this project's conventions, the four tasks, and the constraints above.
Do not emit any code, file listings, implementation steps, or additional sections. Variants must be genuinely distinct architectural strategies for delivering the whole 4-task release, not rearrangements of the same strategy.