@chronicle.app/obsidian 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @chronicle.app/obsidian
+
+Import an Obsidian vault as Markdown documents, without requiring a particular
+folder structure, tagging convention, person note, or custom properties.
+
+## Usage
+
+```bash
+chronicle extract obsidian --input /path/to/vault
+chronicle extract obsidian --input /path/to/vault/Books --limit 1
+```
+
+`--input` accepts a vault or a folder within it. The nearest ancestor containing
+`.obsidian` supplies the vault name and relative paths, so a subfolder import
+uses the same document identities as a full import. Without `.obsidian`, the
+input directory is treated as the vault. `--limit` limits emitted notes (`0`
+means unlimited); all vault note paths remain available for link resolution.
+
+## Imported data
+
+Every `.md` file is imported as a `DocumentObject`, including untagged notes.
+Hidden files/directories, symlinks, and non-Markdown attachments are skipped.
+
+- Identity: `(source, handle, inRealm.handle)`, where `handle` is the complete
+  vault-relative filename and the realm handle is the vault folder name.
+- Name: filename without its extension.
+- Body: Markdown with leading YAML frontmatter omitted; other content, including
+  Dataview syntax and whitespace, is preserved.
+- Tags: the standard frontmatter `tags` property, preserving case and nested tags.
+- References: resolved wikilinks and inline Markdown links to other notes;
+  external HTTP(S) Markdown links reference URL entities.
+- Modification: one `UpdateAction` at the file's modification time, attributed to
+  the Chronicle owner through `@me`. No owner note is needed.
+
+Wikilinks and note embeds support folder paths, display labels, headings and block anchors.
+Relative Markdown note links are resolved against the source note's directory.
+Repeated links are deduplicated. Unresolved or ambiguous targets stay in the
+body without inventing a document. Code examples and comments are ignored when
+recognizing links. This v1 does not parse the entire Markdown grammar: reference
+style links, inline hashtags, and attachment contents remain in the body only.
+
+Custom properties such as `type`, `birthday`, `goodreads_id`, or `letterboxd_url`
+remain in the raw extraction metadata, outside the document body. They do not create people,
+books, `sameAs` edges, or real-world actions. Aliases, including `@me`, do not
+change a document's identity. There is no mapping configuration.
+
+Filesystem birth time, when available, is retained in the raw record as
+`birthtime`. It is not treated as an authored `CreateAction`: copying/restoring
+a file can change it. Modification time records the current file state, not a
+reconstructed history of every edit. Unchanged files have a deterministic
+snapshot time based on the newest imported file modification time.
+
+Notes are extracted newest-modified first, reading each body only when it is
+emitted. Reruns scan every note: an already-imported path may still contain
+edits, so the key-only ETL frontier cannot safely stop the scan. Complete,
+unlimited scans also allow deleted notes to be detected.
+
+The plugin provides `obsidian://open?vault=…&file=…` deep links from document
+identities. Renaming a file changes its path identity; this v1 does not track
+renames. Vaults with the same folder name share the same realm namespace.
+
+## Development
+
+```bash
+npm test --workspace=@chronicle.app/obsidian
+npm run build --workspace=@chronicle.app/obsidian
+```
+
+Tests build a small synthetic vault in a temporary directory and run it through
+the extractor and transformer, so they never read a real vault or other host
+data.

package/dist/connectors/ObsidianExtractor.d.ts

@@ -0,0 +1,51 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import ObsidianTransformer from './ObsidianTransformer.js';
+export interface VaultNote {
+    /** Path relative to the enclosing vault, including .md. */
+    path: string;
+    name: string;
+    tags: string[];
+    frontmatter: {
+        [key: string]: unknown;
+    };
+    /** Markdown after the YAML frontmatter, preserving plugin-specific syntax. */
+    body: string;
+    /** Filesystem birth time, when available; not an authored creation event. */
+    birthtime?: string;
+    mtime: string;
+}
+export interface VaultContext {
+    recordType: string;
+    vault: string;
+    /** All Markdown paths in the vault, including notes outside the input folder. */
+    paths: string[];
+}
+export declare class ObsidianExtractor extends Extractor<typeof ObsidianExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "local";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static temporality: "snapshot";
+    static newestFirst: boolean;
+    static defaultTransformer: typeof ObsidianTransformer;
+    static schema: any;
+    private entries;
+    private context;
+    private newestMtime?;
+    setup(): Promise<void>;
+    /** Prefer the enclosing Obsidian vault so subfolder imports retain identity. */
+    private vaultRoot;
+    /** Re-reading unchanged files produces the same snapshot time. */
+    protected asOfTime(): Date;
+    keyOf(record: Record): string | null;
+    determineCount(): Promise<number | null>;
+    extract(): AsyncGenerator<Record>;
+    private readNote;
+    /** Ignore hidden files/directories and symlinks; only Markdown is imported. */
+    private findMarkdownFiles;
+    private frontmatter;
+    private tags;
+}
+//# sourceMappingURL=ObsidianExtractor.d.ts.map

package/dist/connectors/ObsidianExtractor.js

@@ -0,0 +1,151 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { Extractor } from '@chronicle.app/etl';
+import { load, CORE_SCHEMA } from 'js-yaml';
+import { z } from 'zod';
+import ObsidianTransformer from './ObsidianTransformer.js';
+const FRONTMATTER = /^(?:\uFEFF)?---\r?\n((?:[^\n]*\n)*?)---(?:\r?\n|$)/;
+export class ObsidianExtractor extends Extractor {
+    static source = 'obsidian';
+    static description = 'Notes and links from a vault';
+    static delivery = 'local';
+    static strategy = 'vault';
+    static recordTypes = ['notes'];
+    static default = true;
+    static temporality = 'snapshot';
+    // Paths stay known when notes change. The key-only frontier would stop
+    // after 25 existing notes even if more edits remain, so always scan the vault.
+    static newestFirst = false;
+    static defaultTransformer = ObsidianTransformer;
+    static schema = Extractor.schema.extend({
+        input: z.string().describe('Path to an Obsidian vault or a folder within it'),
+    });
+    entries = [];
+    context;
+    newestMtime;
+    async setup() {
+        this.entries = [];
+        this.newestMtime = undefined;
+        const input = path.resolve(String(this.config.input));
+        const root = await this.vaultRoot(input);
+        const files = await this.findMarkdownFiles(root);
+        this.context = {
+            recordType: 'notes',
+            vault: path.basename(root),
+            paths: files.map(file => path.relative(root, file).split(path.sep).join('/')),
+        };
+        for (const file of files) {
+            const relativeToInput = path.relative(input, file);
+            if (relativeToInput.startsWith(`..${path.sep}`) || relativeToInput === '..')
+                continue;
+            const stat = await fs.stat(file);
+            if (!this.newestMtime || stat.mtime > this.newestMtime)
+                this.newestMtime = stat.mtime;
+            this.entries.push({
+                file,
+                relative: path.relative(root, file).split(path.sep).join('/'),
+                mtime: stat.mtime,
+                ...(stat.birthtimeMs > 0 && {
+                    birthtime: stat.birthtime.toISOString(),
+                }),
+            });
+        }
+        // Newest-first for limited imports; path order breaks ties so a
+        // re-read of an unchanged vault yields the same stream.
+        this.entries.sort((a, b) => b.mtime.getTime() - a.mtime.getTime() || a.relative.localeCompare(b.relative));
+        this.logVerboseStep(`Vault "${this.context.vault}": ${this.entries.length} Markdown notes`);
+    }
+    /** Prefer the enclosing Obsidian vault so subfolder imports retain identity. */
+    async vaultRoot(input) {
+        let dir = input;
+        do {
+            try {
+                if ((await fs.stat(path.join(dir, '.obsidian'))).isDirectory())
+                    return dir;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return input;
+            dir = parent;
+        } while (dir !== path.dirname(dir));
+        return input;
+    }
+    /** Re-reading unchanged files produces the same snapshot time. */
+    asOfTime() {
+        return this.newestMtime ?? super.asOfTime();
+    }
+    keyOf(record) {
+        return record.data.path ?? null;
+    }
+    async determineCount() {
+        const limit = this.getEffectiveLimit();
+        return limit === null ? this.entries.length : Math.min(limit, this.entries.length);
+    }
+    async *extract() {
+        let count = 0;
+        for (const entry of this.entries) {
+            if (this.shouldStopExtracting(count))
+                return;
+            yield this.createRecord(await this.readNote(entry), this.context);
+            count++;
+        }
+    }
+    async readNote(entry) {
+        const body = await fs.readFile(entry.file, 'utf8');
+        const frontmatter = this.frontmatter(body, entry.relative);
+        return {
+            path: entry.relative,
+            name: path.basename(entry.file, path.extname(entry.file)),
+            tags: this.tags(frontmatter),
+            frontmatter,
+            body: body.replace(FRONTMATTER, ''),
+            ...(entry.birthtime !== undefined && { birthtime: entry.birthtime }),
+            mtime: entry.mtime.toISOString(),
+        };
+    }
+    /** Ignore hidden files/directories and symlinks; only Markdown is imported. */
+    async findMarkdownFiles(root) {
+        const files = [];
+        const walk = async (dir) => {
+            for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+                if (entry.name.startsWith('.'))
+                    continue;
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory())
+                    await walk(full);
+                else if (entry.isFile() && path.extname(entry.name).toLowerCase() === '.md')
+                    files.push(full);
+            }
+        };
+        await walk(root);
+        return files.sort((a, b) => a.localeCompare(b));
+    }
+    frontmatter(body, file) {
+        const match = FRONTMATTER.exec(body);
+        if (!match)
+            return {};
+        try {
+            const loaded = load(match[1], { schema: CORE_SCHEMA });
+            if (loaded && typeof loaded === 'object' && !Array.isArray(loaded))
+                return loaded;
+        }
+        catch (error) {
+            this.logger.warn(`Unparseable frontmatter in ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return {};
+    }
+    tags(frontmatter) {
+        const raw = frontmatter.tags;
+        const values = Array.isArray(raw) ? raw : typeof raw === 'string' ? raw.split(/[\s,]+/) : [];
+        return [
+            ...new Set(values
+                .filter((value) => typeof value === 'string')
+                .map(value => value.trim().replace(/^#/, ''))
+                .filter(Boolean)),
+        ];
+    }
+}

package/dist/connectors/ObsidianTransformer.d.ts

@@ -0,0 +1,11 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { UpdateAction } from '@chronicle.app/schema';
+/** Every note is a document; custom properties never infer a real-world subject. */
+export default class ObsidianTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<UpdateAction[]>;
+    private document;
+    private references;
+    /** Resolve only existing notes; never guess among ambiguous basenames. */
+    private resolve;
+}
+//# sourceMappingURL=ObsidianTransformer.d.ts.map

package/dist/connectors/ObsidianTransformer.js

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import { ChronicleTransformer, selfAgent } from '@chronicle.app/etl';
+const SOURCE = 'obsidian';
+const NOTE_KEY = ['source', 'handle', 'inRealm.handle'];
+const withExtension = (value) => (/\.md$/i.test(value) ? value : `${value}.md`);
+/** Every note is a document; custom properties never infer a real-world subject. */
+export default class ObsidianTransformer extends ChronicleTransformer {
+    async transform(record) {
+        if (record.extraction.recordType !== 'notes')
+            return [];
+        const note = record.data;
+        const ctx = record.context;
+        const document = this.document(note.path, ctx);
+        document.body = note.body;
+        document.tags = note.tags;
+        document.references = this.references(note, ctx);
+        return [
+            {
+                '@type': 'UpdateAction',
+                '@key': ['@type', 'source', 'object.handle', 'object.inRealm.handle', 'timestamp'],
+                source: SOURCE,
+                timestamp: note.mtime,
+                agent: selfAgent({ source: SOURCE }),
+                object: document,
+            },
+        ];
+    }
+    document(handle, ctx) {
+        const realm = {
+            '@type': 'Realm',
+            '@key': ['@type', 'source', 'handle'],
+            source: SOURCE,
+            handle: ctx.vault,
+        };
+        return {
+            '@type': 'DocumentObject',
+            '@key': NOTE_KEY,
+            source: SOURCE,
+            handle,
+            name: path.posix.basename(handle, path.posix.extname(handle)),
+            inRealm: realm,
+            mimeType: 'text/markdown',
+        };
+    }
+    references(note, ctx) {
+        const references = new Map();
+        // Ignore code examples and comments when recognizing links. The original
+        // Markdown is preserved verbatim on the document.
+        const text = note.body
+            .replaceAll(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1[^\n]*(?:\n|$)/gm, '')
+            .replaceAll(/(`+)[^\n]*?\1/g, '')
+            .replaceAll(/<!--[^]*?-->|%%[^]*?%%/g, '');
+        const add = (raw, wiki) => {
+            let target = raw.trim();
+            if (/^https?:\/\//i.test(target)) {
+                try {
+                    const url = new URL(target).href;
+                    references.set(url, {
+                        '@type': 'Entity',
+                        '@key': ['url'],
+                        source: 'url',
+                        url,
+                    });
+                }
+                catch {
+                    /* Keep malformed links in the body only. */
+                }
+                return;
+            }
+            if (/^[a-z][a-z\d+.-]*:/i.test(target))
+                return;
+            try {
+                target = decodeURIComponent(target);
+            }
+            catch {
+                return;
+            }
+            target = target.split('#')[0];
+            if (!target)
+                return;
+            const resolved = this.resolve(target, note.path, ctx.paths, wiki);
+            if (resolved && resolved !== note.path)
+                references.set(resolved, this.document(resolved, ctx));
+        };
+        for (const match of text.matchAll(/(?<!\\)\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g))
+            add(match[1], true);
+        for (const match of text.matchAll(/(?<!!)(?<!\\)\[[^\]\n]*\]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+"[^"\n]*")?\s*\)/g))
+            add(match[1] ?? match[2], false);
+        return [...references.values()];
+    }
+    /** Resolve only existing notes; never guess among ambiguous basenames. */
+    resolve(target, from, paths, wiki) {
+        const root = withExtension(path.posix.normalize(target.replace(/^\//, '')));
+        const relative = withExtension(path.posix.normalize(path.posix.join(path.posix.dirname(from), target)));
+        const candidates = wiki && !target.startsWith('.') ? [root, relative] : [relative, root];
+        for (const candidate of candidates)
+            if (paths.includes(candidate))
+                return candidate;
+        if (!wiki || target.startsWith('.'))
+            return undefined;
+        const matches = paths.filter(value => value.endsWith(`/${root}`));
+        return matches.length === 1 ? matches[0] : undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ObsidianExtractor } from './connectors/ObsidianExtractor.js';
+export { default as ObsidianTransformer } from './connectors/ObsidianTransformer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+export { ObsidianExtractor } from './connectors/ObsidianExtractor.js';
+export { default as ObsidianTransformer } from './connectors/ObsidianTransformer.js';

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@chronicle.app/obsidian",
+  "version": "0.3.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [
+    "chronicle",
+    "obsidian"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for Obsidian Markdown documents and note links",
+  "devDependencies": {
+    "@chronicle.app/etl": "0.3.0",
+    "@chronicle.app/schema": "0.3.0",
+    "@chronicle.app/tsconfig": "0.3.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://chronicle.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "plugins/obsidian"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "@chronicle.app/etl": ">=0.1.0 <1.0.0",
+    "@chronicle.app/schema": ">=0.1.0 <1.0.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "chronicle": {
+    "plugin": true,
+    "sources": {
+      "obsidian": {
+        "strategies": {
+          "vault": {
+            "delivery": "local",
+            "recordTypes": [
+              "notes"
+            ],
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}