BTMG — Bidirectional Temporal Memory Graph

Sync between a Neo4j knowledge graph and documentation files (MDX/Markdown) with schema enforcement, bitemporal versioning, and AI-agent tooling via MCP.

Features

• Schema-enforced mutations — Define your graph schema in TypeScript. Every write is validated against Zod schemas compiled from your definition. Unknown labels or properties are rejected (anti-hallucination gate for AI agents).
• Bitemporal versioning — Entity-State pattern with _valid_from/_valid_to (valid time) and _recorded_at (transaction time). Full version history, point-in-time queries, and diff computation.
• Bidirectional sync — Graph state renders to doc files with _sync_hash in frontmatter. Doc changes sync back to the graph. Conflict detection via hash comparison with configurable resolution strategies.
• Audit trail — Every mutation creates an AuditEntry node linked to the entity, queryable by entity, time, or actor.
• MCP server — 9 tools and 5 resources for AI agents to read, write, and query the graph through the Model Context Protocol.
• CLI — Commands for init, sync, snapshot, changelog, validate, query, serve, and migrate.

Install

npm install btmg

Quick Start

1. Define your schema

// btmg.config.ts
import { defineSchema } from "btmg";

export default defineSchema({
  schema: {
    nodes: [
      {
        label: "Concept",
        properties: {
          name: { type: "string", required: true },
          description: { type: "string" },
          tags: { type: "string[]" },
        },
      },
    ],
    edges: [
      {
        type: "RELATES_TO",
        from: "Concept",
        to: "Concept",
      },
    ],
  },
  docs: {
    directory: "./docs",
    format: "md",
  },
});

2. Use the API

import { BTMG } from "btmg";
import config from "./btmg.config.js";

const graph = new BTMG(config);

// Create an entity (validated against schema)
const result = await graph.upsert("Concept", {
  name: "Event Sourcing",
  description: "Store state changes as a sequence of events",
  tags: ["architecture", "pattern"],
});

// Query current state
const entity = await graph.get(result.id);

// Time-travel: get state at a past timestamp
const past = await graph.getAt(result.id, "2024-06-01T00:00:00Z");

// Version history
const changelog = await graph.changelog(result.id);

// Bidirectional sync with docs
const syncResult = await graph.sync({ docsDir: "./docs" });

await graph.close();

3. CLI

# Initialize config
npx btmg init

# Apply schema to Neo4j
npx btmg migrate

# Run bidirectional sync
npx btmg sync --docs ./docs

# Point-in-time snapshot
npx btmg snapshot "2024-06-01T00:00:00Z"

# Validate data against schema
npx btmg validate Concept '{"name": "Test"}'

# Start MCP server
npx btmg serve

4. MCP Server for AI Agents

Add to your MCP client config:

{
  "mcpServers": {
    "btmg": {
      "command": "npx",
      "args": ["btmg", "serve"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password"
      }
    }
  }
}

Tools: upsert, delete, relate, query, sync, snapshot, changelog, diff, validate

Resources: btmg://schema, btmg://entity/{id}, btmg://changelog/{id}, btmg://audit/{id}

Schema Property Types

| Type | Description | |------|-------------| | string | Text | | number | Numeric | | boolean | True/false | | date | ISO date/datetime | | url | Valid URL | | email | Valid email | | enum | One of specified values | | string[] | Array of strings | | json | Arbitrary JSON |

Temporal Model

(Entity) --[CURRENT]--> (State v3)
                          |
                        [PREVIOUS]
                          |
                        (State v2)
                          |
                        [PREVIOUS]
                          |
                        (State v1)

• Entity: Immutable identity (_id, _label, _created_at)
• State: Versioned properties + _valid_from, _valid_to, _recorded_at, _version, _actor
• CURRENT: Always points to the latest state
• PREVIOUS: Chain of historical states

Conflict Resolution

| Strategy | Behavior | |----------|----------| | graph-wins | Graph state overwrites doc (default) | | docs-wins | Doc content overwrites graph | | merge | Doc properties override graph where present | | fail | Throw error on conflict |

License

MIT