@mandays/obsidian-memory-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,538 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+interface Fact {
+    type: "fact";
+    id?: string;
+    entity: string;
+    predicate: string;
+    value: string;
+    valid_from?: string | null;
+    valid_to?: string | null;
+    recorded_at: string;
+    confidence?: "high" | "medium" | "low";
+    sources?: string[];
+    last_reviewed?: string;
+    superseded_by?: string;
+    tags?: string[];
+    decay?: {
+        review_after_days?: number;
+        archive_after_valid_to?: boolean;
+        pin?: boolean;
+    };
+}
+interface ParsedFact {
+    data: Fact;
+    content: string;
+    path: string;
+}
+
+interface Event {
+    type: "event";
+    id?: string;
+    occurred_at: string;
+    summary: string;
+    entities?: string[];
+    kind?: "conversation" | "decision" | "ingest" | "action" | "observation";
+    sources?: string[];
+    derived_facts?: string[];
+}
+interface ParsedEvent {
+    data: Event;
+    content: string;
+    path: string;
+}
+
+type OperationType = "create_fact" | "update_fact" | "add_event" | "archive_fact" | "review_fact" | "rename_entity" | "add_entity" | "add_predicate";
+type OperationStatus = "proposed" | "validated" | "applied" | "rejected" | "conflict" | "superseded";
+interface Operation {
+    type: "operation";
+    operation_id: string;
+    op: OperationType;
+    agent_id: string;
+    created_at: string;
+    target_id?: string;
+    target_path?: string;
+    precondition_hash?: string | null;
+    status: OperationStatus;
+    reason: string;
+    sources?: string[];
+    conflict_reason?: string;
+    applied_at?: string;
+    payload: Record<string, unknown>;
+}
+interface ParsedOperation {
+    data: Operation;
+    content: string;
+    path: string;
+}
+
+interface Claim {
+    type: "claim";
+    target_id: string;
+    operation_id: string;
+    agent_id: string;
+    created_at: string;
+    expires_at: string;
+    heartbeat_at: string;
+    status: "active" | "released" | "broken";
+}
+interface ParsedClaim {
+    data: Claim;
+    path: string;
+}
+
+type EntityKind = "person" | "project" | "org" | "place" | "concept" | "tool";
+interface Entity {
+    id: string;
+    kind: EntityKind;
+    display: string;
+    aliases?: string[];
+}
+interface EntityIndex {
+    type: "entity-index";
+    entities: Entity[];
+}
+
+interface Config {
+    vaultPath: string;
+    transport: "stdio" | "sse";
+    agentId: string;
+    writeMode: "direct" | "inbox";
+    port: number;
+    apiKey?: string;
+    staleDays: number;
+}
+declare const DEFAULT_CONFIG: Omit<Config, "vaultPath" | "agentId">;
+
+interface VaultPaths {
+    root: string;
+    memory: string;
+    facts: string;
+    events: string;
+    schema: string;
+    views: string;
+    inbox: string;
+    claims: string;
+    ops: string;
+    opsApplied: string;
+    archive: string;
+    entities: string;
+    predicates: string;
+    versionYaml: string;
+    sources: string;
+    people: string;
+    projects: string;
+    decisions: string;
+    insights: string;
+    context: string;
+}
+declare class Vault {
+    readonly paths: VaultPaths;
+    readonly config: Config;
+    constructor(config: Config);
+    /**
+     * Assert that the vault path exists and contains a valid v3 version marker.
+     */
+    assertValid(): Promise<void>;
+    /**
+     * Get the relative path from vault root.
+     */
+    relativePath(absolutePath: string): string;
+    /**
+     * Resolve a relative path to absolute from vault root.
+     */
+    resolvePath(relativePath: string): string;
+    /**
+     * Get the fact file path for a given entity and predicate.
+     */
+    factPath(entity: string, predicate: string, suffix?: string): string;
+    /**
+     * Get the event directory path for a given date.
+     */
+    eventDir(date: string): string;
+    /**
+     * Get the inbox ops path for a given agent and operation.
+     */
+    inboxOpPath(agentId: string, operationId: string): string;
+    /**
+     * Get the applied operation receipt path.
+     */
+    appliedOpPath(operationId: string): string;
+    /**
+     * Get the claim path for a target ID.
+     */
+    claimPath(targetId: string): string;
+    /**
+     * Get the archive path for a fact.
+     */
+    archivePath(year: string, entity: string, predicate: string): string;
+    /**
+     * Get the view path for a named view.
+     */
+    viewPath(viewName: string): string;
+    /**
+     * Get entity-specific view path.
+     */
+    entityViewPath(entity: string): string;
+}
+declare class VaultError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+
+declare class EntityRegistry {
+    private cache;
+    private readonly vault;
+    constructor(vault: Vault);
+    /**
+     * Load all entities from entities.md. Uses cache if available.
+     */
+    getAll(): Promise<Entity[]>;
+    /**
+     * Get entities filtered by kind.
+     */
+    getByKind(kind: EntityKind): Promise<Entity[]>;
+    /**
+     * Find a single entity by ID.
+     */
+    findById(id: string): Promise<Entity | undefined>;
+    /**
+     * Check if an entity exists.
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * Add a new entity. Returns the updated list.
+     */
+    add(entity: Entity): Promise<Entity[]>;
+    /**
+     * Invalidate the in-memory cache.
+     */
+    invalidate(): void;
+    private save;
+}
+
+declare class PredicateRegistry {
+    private cache;
+    private readonly vault;
+    constructor(vault: Vault);
+    /**
+     * Load all predicates from predicates.yaml.
+     * Supports both formats:
+     * - Flat array: ["role", "base", ...]
+     * - Object with entries: { predicates: [{id: "role", description: "..."}] }
+     */
+    getAll(): Promise<string[]>;
+    /**
+     * Check if a predicate exists.
+     */
+    exists(predicate: string): Promise<boolean>;
+    /**
+     * Add a new predicate. Returns the updated list.
+     */
+    add(predicate: string): Promise<string[]>;
+    /**
+     * Invalidate the in-memory cache.
+     */
+    invalidate(): void;
+    private save;
+}
+
+interface FactFilter {
+    entity?: string;
+    predicate?: string;
+    id?: string;
+    onDate?: string;
+    confidence?: string;
+    tags?: string[];
+    query?: string;
+    limit?: number;
+}
+interface EventFilter {
+    entity?: string;
+    since?: string;
+    until?: string;
+    kind?: string;
+    limit?: number;
+}
+declare class QueryEngine {
+    private readonly vault;
+    constructor(vault: Vault);
+    /**
+     * Find facts matching the given filters.
+     */
+    findFacts(filter: FactFilter): Promise<ParsedFact[]>;
+    /**
+     * Find a fact by its stable ID.
+     */
+    findFactById(id: string): Promise<ParsedFact | null>;
+    /**
+     * Find events matching the given filters.
+     */
+    findEvents(filter: EventFilter): Promise<ParsedEvent[]>;
+    /**
+     * Find any record (fact, event, operation) by its stable ID.
+     */
+    findById(id: string): Promise<{
+        type: string;
+        path: string;
+        data: Record<string, unknown>;
+    } | null>;
+    private matchesFactFilter;
+    private matchesEventFilter;
+    /**
+     * Check if a fact is temporally valid on a given date.
+     * valid_from <= date <= valid_to (with null meaning unbounded)
+     */
+    private isTemporallyValid;
+    private applyLimit;
+}
+
+interface CreateFactParams {
+    entity: string;
+    predicate: string;
+    value: string;
+    confidence?: "high" | "medium" | "low";
+    valid_from?: string | null;
+    valid_to?: string | null;
+    sources?: string[];
+    tags?: string[];
+    reason: string;
+    id?: string;
+}
+interface UpdateFactParams {
+    targetId?: string;
+    targetPath?: string;
+    value?: string;
+    valid_to?: string | null;
+    confidence?: "high" | "medium" | "low";
+    tags?: string[];
+    last_reviewed?: string;
+    reason: string;
+}
+interface AddEventParams {
+    summary: string;
+    entities?: string[];
+    kind?: "conversation" | "decision" | "ingest" | "action" | "observation";
+    sources?: string[];
+    body?: string;
+    reason?: string;
+}
+interface ArchiveFactParams {
+    targetId?: string;
+    targetPath?: string;
+    reason: string;
+}
+interface CompactResult {
+    applied: number;
+    conflicts: number;
+    archived: number;
+    errors: string[];
+}
+declare class OperationManager {
+    private readonly vault;
+    private readonly agentId;
+    constructor(vault: Vault, agentId: string);
+    /**
+     * Create a fact directly (single-agent mode).
+     */
+    createFactDirect(params: CreateFactParams): Promise<{
+        path: string;
+        id: string;
+    }>;
+    /**
+     * Create an operation envelope for creating a fact (inbox mode).
+     */
+    createFactEnvelope(params: CreateFactParams): Promise<{
+        path: string;
+        operationId: string;
+    }>;
+    /**
+     * Update a fact directly (single-agent mode).
+     */
+    updateFactDirect(params: UpdateFactParams): Promise<{
+        path: string;
+        hash: string;
+    }>;
+    /**
+     * Create an operation envelope for updating a fact (inbox mode).
+     */
+    updateFactEnvelope(params: UpdateFactParams): Promise<{
+        path: string;
+        operationId: string;
+    }>;
+    /**
+     * Add an event directly.
+     */
+    addEventDirect(params: AddEventParams): Promise<{
+        path: string;
+        id: string;
+    }>;
+    /**
+     * Create an operation envelope for adding an event (inbox mode).
+     */
+    addEventEnvelope(params: AddEventParams): Promise<{
+        path: string;
+        operationId: string;
+    }>;
+    /**
+     * Archive a fact directly.
+     */
+    archiveFactDirect(params: ArchiveFactParams): Promise<{
+        archivePath: string;
+    }>;
+    /**
+     * Compact inbox: validate and apply all proposed operations.
+     */
+    compact(autoApply?: boolean): Promise<CompactResult>;
+    private applyOperation;
+    private markConflict;
+    private moveToApplied;
+    private checkClaim;
+    private resolveFactPath;
+}
+declare class OperationError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+
+interface LintFinding {
+    level: "ERROR" | "WARN";
+    path: string;
+    message: string;
+}
+declare class SchemaValidator {
+    private readonly vault;
+    private readonly entities;
+    private readonly predicates;
+    constructor(vault: Vault, entities: EntityRegistry, predicates: PredicateRegistry);
+    /**
+     * Run full vault validation. Returns findings array. Empty = valid.
+     */
+    lint(): Promise<LintFinding[]>;
+    private checkVersion;
+    private validateFacts;
+    private validateEvents;
+    private validateOperations;
+    private checkDuplicateIds;
+    private checkContradictions;
+    private temporalOverlap;
+    private validateWikilinks;
+}
+
+declare class ViewGenerator {
+    private readonly vault;
+    private readonly staleDays;
+    constructor(vault: Vault, staleDays?: number);
+    /**
+     * Rebuild all materialized views. Returns list of files written.
+     */
+    rebuildAll(): Promise<string[]>;
+    private writeView;
+    private loadAllFacts;
+    private loadAllEvents;
+    private loadAllOperations;
+    private loadAllClaims;
+    private groupByEntity;
+    private renderByEntity;
+    private renderById;
+    private renderByPredicate;
+    private renderTimeline;
+    private renderContradictions;
+    private renderStale;
+    private renderGraph;
+    private renderInbox;
+    private renderOperations;
+    private renderClaims;
+    private renderConflicts;
+}
+
+/**
+ * Create and configure the MCP server with all tools registered.
+ */
+declare function createServer(config: Config): McpServer;
+
+interface ConfigInput {
+    vault?: string;
+    transport?: string;
+    agentId?: string;
+    mode?: string;
+    port?: number;
+    apiKey?: string;
+    staleDays?: number;
+}
+/**
+ * Resolve configuration from CLI args, env vars, and defaults.
+ */
+declare function resolveConfig(input: ConfigInput): Config;
+
+interface ScaffoldOptions {
+    vaultPath: string;
+    entities?: Entity[];
+    predicates?: string[];
+}
+/**
+ * Scaffold a new v3 vault with all required directories and schema files.
+ */
+declare function scaffoldVault(options: ScaffoldOptions): Promise<string[]>;
+
+/**
+ * Generate an operation ID matching the pattern: op-{YYYYMMDDTHHMMSSz}-{4-byte-hex}
+ */
+declare function generateOperationId(): string;
+/**
+ * Generate an agent ID matching the pattern: agent-{slug}-{8-char-hex}
+ */
+declare function generateAgentId(name?: string): string;
+/**
+ * Generate a fact ID: fact-{entity}-{predicate}
+ */
+declare function generateFactId(entity: string, predicate: string): string;
+/**
+ * Generate an event ID: event-{YYYY-MM-DD}-{slug}
+ */
+declare function generateEventId(date: string, slug: string): string;
+/**
+ * Slugify a string for use in filenames and IDs.
+ */
+declare function slugify(text: string): string;
+
+/**
+ * Compute the SHA-256 hash of a file, returning "sha256:{64-hex}" format.
+ */
+declare function computeFileHash(filePath: string): Promise<string>;
+/**
+ * Compute the SHA-256 hash of a string, returning "sha256:{64-hex}" format.
+ */
+declare function computeStringHash(content: string): string;
+/**
+ * Validate that a hash string matches the expected pattern.
+ */
+declare function isValidHash(hash: string): boolean;
+
+interface ParsedMarkdown {
+    data: Record<string, unknown>;
+    content: string;
+    path: string;
+}
+/**
+ * Parse a markdown file's YAML frontmatter and body content.
+ */
+declare function parseMarkdownFile(filePath: string): Promise<ParsedMarkdown>;
+/**
+ * Serialize frontmatter data and optional body into a markdown string.
+ */
+declare function serializeMarkdown(data: Record<string, unknown>, body?: string): string;
+/**
+ * Write a markdown file atomically (write to .tmp then rename).
+ */
+declare function writeMarkdownFile(filePath: string, data: Record<string, unknown>, body?: string): Promise<void>;
+/**
+ * Read only the frontmatter of a markdown file without the full body.
+ */
+declare function readFrontmatter(filePath: string): Promise<Record<string, unknown>>;
+/**
+ * Check if a file exists.
+ */
+declare function fileExists(filePath: string): Promise<boolean>;
+
+export { type Claim, type Config, type ConfigInput, DEFAULT_CONFIG, type Entity, type EntityIndex, type EntityKind, EntityRegistry, type Event, type Fact, type LintFinding, type Operation, OperationError, OperationManager, type OperationStatus, type OperationType, type ParsedClaim, type ParsedEvent, type ParsedFact, type ParsedMarkdown, type ParsedOperation, PredicateRegistry, QueryEngine, SchemaValidator, Vault, VaultError, ViewGenerator, computeFileHash, computeStringHash, createServer, fileExists, generateAgentId, generateEventId, generateFactId, generateOperationId, isValidHash, parseMarkdownFile, readFrontmatter, resolveConfig, scaffoldVault, serializeMarkdown, slugify, writeMarkdownFile };

package/dist/index.js

@@ -0,0 +1,55 @@
+import {
+  EntityRegistry,
+  OperationError,
+  OperationManager,
+  PredicateRegistry,
+  QueryEngine,
+  SchemaValidator,
+  Vault,
+  VaultError,
+  ViewGenerator,
+  computeFileHash,
+  computeStringHash,
+  createServer,
+  fileExists,
+  generateAgentId,
+  generateEventId,
+  generateFactId,
+  generateOperationId,
+  isValidHash,
+  parseMarkdownFile,
+  readFrontmatter,
+  resolveConfig,
+  scaffoldVault,
+  serializeMarkdown,
+  slugify,
+  writeMarkdownFile
+} from "./chunk-5U2LXK3W.js";
+export {
+  EntityRegistry,
+  OperationError,
+  OperationManager,
+  PredicateRegistry,
+  QueryEngine,
+  SchemaValidator,
+  Vault,
+  VaultError,
+  ViewGenerator,
+  computeFileHash,
+  computeStringHash,
+  createServer,
+  fileExists,
+  generateAgentId,
+  generateEventId,
+  generateFactId,
+  generateOperationId,
+  isValidHash,
+  parseMarkdownFile,
+  readFrontmatter,
+  resolveConfig,
+  scaffoldVault,
+  serializeMarkdown,
+  slugify,
+  writeMarkdownFile
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@mandays/obsidian-memory-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Obsidian v3 Atomic Markdown Memory vaults",
+  "type": "module",
+  "bin": {
+    "obsidian-memory-mcp": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx bin/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/ bin/",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "obsidian",
+    "memory",
+    "ai",
+    "model-context-protocol",
+    "markdown"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "commander": "^12.1.0",
+    "date-fns": "^4.1.0",
+    "express": "^5.1.0",
+    "glob": "^11.0.0",
+    "gray-matter": "^4.0.3",
+    "js-yaml": "^4.1.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.0",
+    "eslint": "^9.16.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}