feat: add Obsidian vault backend with read-write support

Full Obsidian backend: markdown parsing, block-level CRUD, file watching,
inverted search index, HTTP/SSE transport, and decision tracking tools.
Security hardened: path traversal protection, full mutex locking, input validation.
195 tests passing, race detector clean.

Author: skridlevsky

README.md

@@ -0,0 +1,94 @@
+package backend
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/skridlevsky/graphthulhu/types"
+)
+
+// Backend is the interface every knowledge graph backend must implement.
+// The Logseq client (client.Client) satisfies this interface.
+// Future backends (e.g. Obsidian vault) implement the same contract.
+type Backend interface {
+	// Core read operations
+	GetAllPages(ctx context.Context) ([]types.PageEntity, error)
+	GetPage(ctx context.Context, nameOrID any) (*types.PageEntity, error)
+	GetPageBlocksTree(ctx context.Context, nameOrID any) ([]types.BlockEntity, error)
+	GetBlock(ctx context.Context, uuid string, opts ...map[string]any) (*types.BlockEntity, error)
+	GetPageLinkedReferences(ctx context.Context, nameOrID any) (json.RawMessage, error)
+
+	// Query operations
+	DatascriptQuery(ctx context.Context, query string, inputs ...any) (json.RawMessage, error)
+
+	// Write operations
+	CreatePage(ctx context.Context, name string, properties map[string]any, opts map[string]any) (*types.PageEntity, error)
+	AppendBlockInPage(ctx context.Context, page string, content string) (*types.BlockEntity, error)
+	PrependBlockInPage(ctx context.Context, page string, content string) (*types.BlockEntity, error)
+	InsertBlock(ctx context.Context, srcBlock any, content string, opts map[string]any) (*types.BlockEntity, error)
+	UpdateBlock(ctx context.Context, uuid string, content string, opts ...map[string]any) error
+	RemoveBlock(ctx context.Context, uuid string) error
+	MoveBlock(ctx context.Context, uuid string, targetUUID string, opts map[string]any) error
+
+	// Page management
+	DeletePage(ctx context.Context, name string) error
+	RenamePage(ctx context.Context, oldName, newName string) error
+
+	// Connectivity
+	Ping(ctx context.Context) error
+}
+
+// HasDataScript is a marker interface for backends supporting DataScript queries.
+// Logseq implements this; Obsidian does not.
+type HasDataScript interface {
+	HasDataScript()
+}
+
+// TagSearcher is implemented by backends that support tag search without DataScript.
+type TagSearcher interface {
+	FindBlocksByTag(ctx context.Context, tag string, includeChildren bool) ([]TagResult, error)
+}
+
+// PropertySearcher is implemented by backends that support property search without DataScript.
+type PropertySearcher interface {
+	FindByProperty(ctx context.Context, key, value, operator string) ([]PropertyResult, error)
+}
+
+// JournalSearcher is implemented by backends that support journal search without DataScript.
+type JournalSearcher interface {
+	SearchJournals(ctx context.Context, query string, from, to string) ([]JournalResult, error)
+}
+
+// FullTextSearcher is implemented by backends with an inverted index for efficient full-text search.
+// When available, tools/search.go uses this instead of brute-force scanning.
+type FullTextSearcher interface {
+	FullTextSearch(ctx context.Context, query string, limit int) ([]SearchHit, error)
+}
+
+// SearchHit is a block found by full-text search.
+type SearchHit struct {
+	PageName string `json:"page"`
+	UUID     string `json:"uuid"`
+	Content  string `json:"content"`
+}
+
+// TagResult holds a block found by tag search, grouped by page.
+type TagResult struct {
+	Page   string             `json:"page"`
+	Blocks []types.BlockEntity `json:"blocks"`
+}
+
+// PropertyResult holds a page or block found by property search.
+type PropertyResult struct {
+	Type       string         `json:"type"` // "page" or "block"
+	Name       string         `json:"name,omitempty"`
+	UUID       string         `json:"uuid,omitempty"`
+	Properties map[string]any `json:"properties"`
+}
+
+// JournalResult holds a journal entry found by search.
+type JournalResult struct {
+	Date    string              `json:"date"`
+	Page    string              `json:"page"`
+	Blocks  []types.BlockEntity `json:"blocks"`
+}

backend/backend.go

@@ -166,6 +166,12 @@ func (c *Client) DeletePage(ctx context.Context, name string) error {
 	return err
 }
 
+// RenamePage renames a page. Logseq handles link updates automatically.
+func (c *Client) RenamePage(ctx context.Context, oldName, newName string) error {
+	_, err := c.call(ctx, "logseq.Editor.renamePage", oldName, newName)
+	return err
+}
+
 // --- Block Operations ---
 
 // GetBlock returns a block by UUID.
@@ -289,3 +295,7 @@ func (c *Client) Ping(ctx context.Context) error {
 	_, err := c.call(ctx, "logseq.Editor.getCurrentPage")
 	return err
 }
+
+// HasDataScript marks the Logseq client as supporting DataScript queries.
+// Implements backend.HasDataScript.
+func (c *Client) HasDataScript() {}

client/logseq.go

@@ -5,7 +5,11 @@ go 1.24.11
 require github.com/modelcontextprotocol/go-sdk v1.2.0
 
 require (
+	github.com/fsnotify/fsnotify v1.9.0 // indirect
 	github.com/google/jsonschema-go v0.3.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	golang.org/x/oauth2 v0.30.0 // indirect
+	golang.org/x/sys v0.13.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.mod

@@ -1,14 +1,23 @@
+github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
+github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
 github.com/golang-jwt/jwt/v5 v5.2.2 h1:Rl4B7itRWVtYIHFrSNd7vhTiz9UpLdi6gZhZ3wEeDy8=
 github.com/golang-jwt/jwt/v5 v5.2.2/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/jsonschema-go v0.3.0 h1:6AH2TxVNtk3IlvkkhjrtbUc4S8AvO0Xii0DxIygDg+Q=
 github.com/google/jsonschema-go v0.3.0/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/modelcontextprotocol/go-sdk v1.2.0 h1:Y23co09300CEk8iZ/tMxIX1dVmKZkzoSBZOpJwUnc/s=
 github.com/modelcontextprotocol/go-sdk v1.2.0/go.mod h1:6fM3LCm3yV7pAs8isnKLn07oKtB0MP9LHd3DfAcKw10=
 github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
 github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 golang.org/x/oauth2 v0.30.0 h1:dnDm7JmhM45NNpd8FDDeLhK6FwqbOf4MLCM9zb1BOHI=
 golang.org/x/oauth2 v0.30.0/go.mod h1:B++QgG3ZKulg6sRPGD/mqlHQs5rB3Ml9erfeDY7xKlU=
+golang.org/x/sys v0.13.0 h1:Af8nKPmuFypiUBjVoU9V20FiaFXOcuZI21p0ycVYYGE=
+golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/tools v0.34.0 h1:qIpSLOxeCYGg9TrcJokLBG4KFA6d795g0xkBkiESGlo=
 golang.org/x/tools v0.34.0/go.mod h1:pAP9OwEaY1CAW3HOmg3hLZC5Z0CCmzjAF2UQMSqNARg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

go.sum

@@ -3,12 +3,57 @@ package graph
 import (
 	"context"
 	"strings"
+	"sync"
+	"time"
 
-	"github.com/skridlevsky/graphthulhu/client"
+	"github.com/skridlevsky/graphthulhu/backend"
 	"github.com/skridlevsky/graphthulhu/parser"
 	"github.com/skridlevsky/graphthulhu/types"
 )
 
+// Cache holds a recently built graph to avoid rebuilding on every analyze call.
+type Cache struct {
+	mu      sync.Mutex
+	graph   *Graph
+	built   time.Time
+	ttl     time.Duration
+	backend backend.Backend
+}
+
+// NewCache creates a graph cache with the given TTL.
+func NewCache(b backend.Backend, ttl time.Duration) *Cache {
+	return &Cache{
+		backend: b,
+		ttl:     ttl,
+	}
+}
+
+// Get returns a cached graph or builds a fresh one if expired.
+func (c *Cache) Get(ctx context.Context) (*Graph, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if c.graph != nil && time.Since(c.built) < c.ttl {
+		return c.graph, nil
+	}
+
+	g, err := Build(ctx, c.backend)
+	if err != nil {
+		return nil, err
+	}
+
+	c.graph = g
+	c.built = time.Now()
+	return g, nil
+}
+
+// Invalidate forces the next Get to rebuild.
+func (c *Cache) Invalidate() {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.graph = nil
+}
+
 // Graph is an in-memory representation of the knowledge graph's link structure.
 type Graph struct {
 	// Forward links: page name (lowercase) → set of linked page names (original case)
@@ -22,7 +67,7 @@ type Graph struct {
 }
 
 // Build fetches all pages and their block trees, constructing the link graph.
-func Build(ctx context.Context, c *client.Client) (*Graph, error) {
+func Build(ctx context.Context, c backend.Backend) (*Graph, error) {
 	pages, err := c.GetAllPages(ctx)
 	if err != nil {
 		return nil, err

graph/builder.go

@@ -4,13 +4,16 @@ import (
 	"context"
 	"flag"
 	"fmt"
+	"net/http"
 	"os"
 	"path/filepath"
 	"strings"
 	"time"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/skridlevsky/graphthulhu/backend"
 	"github.com/skridlevsky/graphthulhu/client"
+	"github.com/skridlevsky/graphthulhu/vault"
 )
 
 var version = "dev"
@@ -57,30 +60,97 @@ func main() {
 func runServe(args []string) {
 	fs := flag.NewFlagSet("serve", flag.ExitOnError)
 	readOnly := fs.Bool("read-only", false, "Disable all write operations")
+	backendType := fs.String("backend", "", "Backend type: logseq (default) or obsidian")
+	vaultPath := fs.String("vault", "", "Path to Obsidian vault (required for obsidian backend)")
+	dailyFolder := fs.String("daily-folder", "daily notes", "Daily notes subfolder name (obsidian only)")
+	httpAddr := fs.String("http", "", "HTTP address to listen on (e.g. :8080). Uses streamable HTTP transport instead of stdio.")
 	fs.Parse(args)
 
-	lsClient := client.New("", "")
-	checkGraphVersionControl(lsClient)
+	// Resolve backend from flag or environment.
+	bt := *backendType
+	if bt == "" {
+		bt = os.Getenv("GRAPHTHULHU_BACKEND")
+	}
+	if bt == "" {
+		bt = "logseq"
+	}
 
-	srv := newServer(lsClient, *readOnly)
-	if err := srv.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
-		fmt.Fprintf(os.Stderr, "graphthulhu: %v\n", err)
+	var b backend.Backend
+	switch bt {
+	case "obsidian":
+		vp := *vaultPath
+		if vp == "" {
+			vp = os.Getenv("OBSIDIAN_VAULT_PATH")
+		}
+		if vp == "" {
+			fmt.Fprintf(os.Stderr, "graphthulhu: --vault or OBSIDIAN_VAULT_PATH required for obsidian backend\n")
+			os.Exit(1)
+		}
+		vc := vault.New(vp, vault.WithDailyFolder(*dailyFolder))
+		if err := vc.Load(); err != nil {
+			fmt.Fprintf(os.Stderr, "graphthulhu: failed to load vault: %v\n", err)
+			os.Exit(1)
+		}
+		vc.BuildBacklinks()
+		
+		// Start file watcher.
+		if err := vc.Watch(); err != nil {
+			fmt.Fprintf(os.Stderr, "graphthulhu: failed to start watcher: %v\n", err)
+			os.Exit(1)
+		}
+		defer vc.Close()
+		
+		b = vc
+	case "logseq":
+		lsClient := client.New("", "")
+		checkGraphVersionControl(lsClient)
+		b = lsClient
+	default:
+		fmt.Fprintf(os.Stderr, "graphthulhu: unknown backend %q (use logseq or obsidian)\n", bt)
 		os.Exit(1)
 	}
+
+	srv := newServer(b, *readOnly)
+
+	if *httpAddr != "" {
+		// Streamable HTTP transport — serves multiple clients.
+		handler := mcp.NewStreamableHTTPHandler(func(r *http.Request) *mcp.Server {
+			return srv
+		}, nil)
+		fmt.Fprintf(os.Stderr, "graphthulhu: listening on %s\n", *httpAddr)
+		if err := http.ListenAndServe(*httpAddr, handler); err != nil {
+			fmt.Fprintf(os.Stderr, "graphthulhu: %v\n", err)
+			os.Exit(1)
+		}
+	} else {
+		// Default: stdio transport for MCP client integration.
+		if err := srv.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
+			fmt.Fprintf(os.Stderr, "graphthulhu: %v\n", err)
+			os.Exit(1)
+		}
+	}
 }
 
 func printUsage() {
-	fmt.Fprintf(os.Stderr, "graphthulhu %s — Logseq knowledge graph server & CLI\n\n", version)
+	fmt.Fprintf(os.Stderr, "graphthulhu %s — Knowledge graph MCP server & CLI\n\n", version)
 	fmt.Fprintf(os.Stderr, "Usage:\n")
-	fmt.Fprintf(os.Stderr, "  graphthulhu                     Start MCP server (default)\n")
-	fmt.Fprintf(os.Stderr, "  graphthulhu serve [--read-only]  Start MCP server (explicit)\n")
+	fmt.Fprintf(os.Stderr, "  graphthulhu                     Start MCP server (default, Logseq)\n")
+	fmt.Fprintf(os.Stderr, "  graphthulhu serve [flags]        Start MCP server\n")
 	fmt.Fprintf(os.Stderr, "  graphthulhu journal [flags] TEXT Append block to today's journal\n")
 	fmt.Fprintf(os.Stderr, "  graphthulhu add -p PAGE TEXT     Append block to a page\n")
 	fmt.Fprintf(os.Stderr, "  graphthulhu search QUERY         Full-text search across the graph\n")
 	fmt.Fprintf(os.Stderr, "  graphthulhu version              Print version\n")
+	fmt.Fprintf(os.Stderr, "\nServe flags:\n")
+	fmt.Fprintf(os.Stderr, "  --backend logseq|obsidian       Backend type (default: logseq)\n")
+	fmt.Fprintf(os.Stderr, "  --vault PATH                    Obsidian vault path\n")
+	fmt.Fprintf(os.Stderr, "  --daily-folder NAME             Daily notes folder (default: daily notes)\n")
+	fmt.Fprintf(os.Stderr, "  --read-only                     Disable write operations\n")
+	fmt.Fprintf(os.Stderr, "  --http ADDR                     Listen on HTTP (e.g. :8080) instead of stdio\n")
 	fmt.Fprintf(os.Stderr, "\nAll CLI commands read from stdin when no TEXT argument is given.\n")
 	fmt.Fprintf(os.Stderr, "Environment: LOGSEQ_API_URL (default http://127.0.0.1:12315)\n")
 	fmt.Fprintf(os.Stderr, "             LOGSEQ_API_TOKEN\n")
+	fmt.Fprintf(os.Stderr, "             GRAPHTHULHU_BACKEND   Backend type\n")
+	fmt.Fprintf(os.Stderr, "             OBSIDIAN_VAULT_PATH   Obsidian vault path\n")
 }
 
 // checkGraphVersionControl warns on stderr if the Logseq graph is not git-controlled.

main.go

@@ -15,7 +15,7 @@ var (
 	blockRefPattern = regexp.MustCompile(`\(\(([0-9a-f-]{36})\)\)`)
 
 	// #tag or #[[multi word tag]] — tags
-	tagPattern      = regexp.MustCompile(`(?:^|\s)#([a-zA-Z0-9_-]+)`)
+	tagPattern = regexp.MustCompile(`(?:^|\s)#([a-zA-Z0-9_-]+)`)
 	tagBracketPattern = regexp.MustCompile(`#\[\[([^\]]+)\]\]`)
 
 	// key:: value — inline properties