Markdown Interoperability

Markdown Interoperability

Memory Journal is built to be an open ecosystem, inherently rejecting data lock-in.

While legacy options let you export the entire database to a single massive JSON blob, our Markdown Interoperability tools allow you to perfectly sync, route, and natively interoperate your memory database against individual Markdown files.

This means your journal entries can natively live inside your Obsidian Vault, Logseq folder, or Git-backed CMS—and be losslessly imported right back into the MCP server when you move between environments.

---

The Concept: Files as the Source of Truth

The system uses standard YAML Frontmatter layered on top of markdown body text to map exact SQL shapes. This standard relies on the same universally recognized attributes mapped to the JSON API, eliminating friction.

⬇️ Exporting a Vault (export_markdown)

When you run export_markdown, the MCP server recursively grabs every entry out of SQLite and converts it to a standard .md flat file.

You execute the command by defining an output_dir (e.g., ../my-vault or C:\Users\chris\obsidian), and the application handles the rest:

{
  "output_dir": "C:\\Users\\chris\\Documents\\obsidian\\MemoryJournal",
  "tags": ["architecture"],
  "limit": 500
}

Results: The system renders a localized file named after an SEO-friendly slug of the entry's timestamp and content tag mapping, outputting semantic Markdown. Example file generated: 2026-04-08-auth-spec-planning.md.

Inside the file, everything is structurally preserved:

---
id: 813
timestamp: 2026-04-08T13:19:43.775Z
entry_type: retrospective
tags:
  - session-summary
  - testing
  - markdown-interoperability
is_personal: true
significance_type: null
project_number: null
issue_number: null
pr_number: null
---

Session Summary: Markdown Interoperability Testing (Phase 3)

**1. Accomplished in this Session**
- Successfully finalized the rigorous Phase 3 Testing infrastructure...

⬆️ Importing a Vault (import_markdown)

Conversely, you can pull massive troves of .md files into the Memory Journal directly from your OS. Point the tool at any mapped folder structure, and Memory Journal sweeps the directories for .md files containing YAML.

It runs validation logic parsing strict zod patterns over the frontmatter.

{
  "source_dir": "C:\\Users\\chris\\Documents\\obsidian\\MemoryJournal",
  "dry_run": true
}

Dry Run Warning: Always ensure you execute an import with dry_run: true on an untested vault first! The system will simulate the mapping algorithms but prevent writes, confirming exactly how many valid structural rows the system identified vs how many parse errors it hit.

Resolving Updates vs. Creates

When iterating over the directories, if the YAML frontmatter explicitly carries an id: integer metric mapping matching the local host, the system fires an Update instead of an Insert. This ensures no data is duplicated across roundtrip exports and imports.

---

🛡️ Security Boundaries & Pathing

All file access is aggressively strictly guarded. If an agent hallucinates or maliciously attempts a path traversal attack to peek into or execute operations on forbidden system components (e.g., ../../../../etc/passwd or \\Windows\\System32), the assertSafeDirectoryPath guard immediately forces an internal panic and safely exits the tool response boundary returning a structured {success: false} payload error.

🤝 Code Mode Namespace (mj.io)

Like all systems in the Memory Journal environment, these tools have full, zero-latency implementations within Code Mode (mj_execute_code). Both standard JSON mapping and File Markdown execution are housed under a localized mj.io namespace logic object.

// Export directly inside the sandbox mapping
const report = await mj.io.exportMarkdown({
    output_dir: 'cm_test_export',
    limit: 5
})

// Return simulation checks from the same process
const integrationTest = await mj.io.importMarkdown({
    source_dir: 'cm_test_export',
    dry_run: true
})

👯 Team Collaboration Integration

This exact workflow scales structurally into the Team Collaborative capabilities mapping, guaranteeing equivalent feature parity.

You can map an environment with team_export_markdown and team_import_markdown. The only differential is that the YAML Frontmatter cleanly manages resolution parsing on the author attribution metric inherently across the multi-client network.

Scope	Tool	Description
Standard	export_markdown	Dumps SQLite to .md with yaml-frontmatter
Standard	import_markdown	Recursively imports and upserts .md directories to DB
Team	team_export_markdown	Dumps the shared Team DB array
Team	team_import_markdown	Upserts .md collections resolving author configuration