Obsidian-agent-bridge – let AI agents read, write, and deepen Obsidian vaults

Notifications You must be signed in to change notification settings

Fork 0

Star 1

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

2 Commits

2 Commits

examples

examples

src

src

.gitignore

.gitignore

LICENSE

LICENSE

README.md

README.md

index.js

index.js

package.json

package.json

Repository files navigation

Give an AI agent read/write/deepen access to your real Obsidian vault as a living knowledge graph.

Zero dependencies. Works with any LLM framework.

Why this exists

Most AI memory systems are databases. They store what happened and retrieve it when relevant. That works fine until you want your agent to actually understand something — to fold a new observation into existing knowledge, connect it to related ideas, and let the graph grow from experience.

This library bridges your AI agent to a real Obsidian vault through the Local REST API plugin. The standout function is deepenNode(): it reads an existing knowledge node, folds new content into the right section without duplicating anything, and keeps your [[wikilinks]] accurate so the graph view stays clean.

Install

npm install obsidian-agent-bridge

Prerequisites:

Obsidian installed and running

Local REST API plugin enabled (runs on port 27124)

Your API key from the plugin settings

Quick start

const { ObsidianGraph } = require('obsidian-agent-bridge');

const graph = new ObsidianGraph({ apiKey: 'your-api-key-here' });

// Deepen a node — reads, folds in new knowledge, deduplicates, writes back const result = await graph.deepenNode( 'Knowledge/TRUST.md', '## Observations', 'Trust rebuilds faster when the betrayer acknowledges impact over intent.', ['BETRAYAL', 'FORGIVENESS'] // wikilinks to ensure are present );

console.log(result); // { written: true, reason: 'appended' } // or { written: false, reason: 'duplicate' } if content already exists

API

new ObsidianGraph(options)

Option Type Required Default

apiKey string yes —

host string no 127.0.0.1

port number no 27124

graph.deepenNode(vaultPath, heading, content, links?)

The core function. Reads a node, folds new content into the target section, deduplicates, manages wikilinks.

await graph.deepenNode( 'Knowledge/Social-Emotional/GRIEF.md', // path inside your vault '## Observations', // section to append under (created if missing) 'Grief and relief can coexist without contradiction.', ['GUILT', 'SELF_COMPASSION'] // optional: wikilinks to ensure are present );

Returns { written: boolean, reason: 'appended' | 'duplicate' }.

graph.appendObservation(vaultPath, observation, links?)

Shorthand for filing a timestamped observation to the ## Observations section.

await graph.appendObservation( 'Knowledge/LOVE.md', 'Unconditional regard holds even through early conflict.', ['ATTACHMENT_STYLES', 'TRUST'] );

graph.readNode(vaultPath)

Read and parse a node. Returns { raw, sections } or null if not found.

graph.ensureNode(vaultPath, initialContent)

Create a node if it does not exist. No-op if it already does.

await graph.ensureNode('Knowledge/NEW_TOPIC.md', # NEW TOPIC\n\n## Overview\n\n);

graph.listLinks(vaultPath)

Return all [[wikilinks]] found in a node.

Lower-level: ObsidianClient

If you just need raw read/write/append without the graph layer:

const { ObsidianClient } = require('obsidian-agent-bridge');

const client = new ObsidianClient({ apiKey: 'your-key' });

const content = await client.read('Notes/something.md'); // string or null await client.write('Notes/something.md', '# Hello\n\n'); // create or overwrite await client.append('Notes/something.md', '\nNew line.'); // append const exists = await client.exists('Notes/something.md'); // boolean

How the Local REST API plugin works

The plugin runs an HTTPS server on port 27124 with a self-signed certificate. This library handles the quirks for you:

rejectUnauthorized: false for the self-signed cert

Content-Type must be text/markdown for writes (not JSON)

Each path segment is individually encodeURIComponent'd

Your API key is in the plugin settings under Obsidian → Settings → Local REST API.

Use with an AI agent

The intended use is wiring deepenNode into your agent's tool calls so it can build knowledge from experience:

// In your LLM tool handler: tools: { async file_observation({ node, observation, related_nodes }) { return graph.deepenNode( Knowledge/${node}.md, '## Observations', observation, related_nodes ); } }

The agent observes something relevant, files it to the right node, and the vault grows. The dedup check means the agent can call this freely without worrying about creating noise.

Run the tests

node examples/quickstart.js

This verifies the parse/render/dedup logic without needing a live Obsidian instance.

License

MIT

About

Give an AI agent read/write/deepen access to your real Obsidian vault as a living knowledge graph. Zero dependencies. Works with any LLM framework.

Topics

knowledge-graph

obsidian

ai-agents

local-first

second-brain

llm

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks

Report repository

Releases 1

v0.1.0 — Initial release

Latest

Jun 6, 2026

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

JavaScript 100.0%