Skip to content

IO

Jump to bottom
Chris & Mike edited this page Apr 21, 2026 · 2 revisions

Data Export

Export project context and development history in JSON or Markdown formats for archival, analysis, or team sharing.

Overview

The export_entries tool lets you export project context for:

  • Backups
  • Reports
  • Sharing
  • Documentation
  • Migration

Formats:

  • JSON (structured data)
  • Markdown (human-readable)

Basic Usage

Export All Entries (JSON)

export_entries({
  format: "json",
});

Output:

[
  {
    "id": 42,
    "entry_type": "technical_achievement",
    "content": "Implemented lazy loading for ML dependencies...",
    "timestamp": "2025-10-04 16:45:30",
    "is_personal": false,
    "tags": ["performance", "optimization", "ml"],
    "significance_type": "technical_breakthrough",
    "auto_context": {
      "repo_name": "memory-journal-mcp",
      "branch": "main",
      ...
    }
  },
  ...
]

Export All Entries (Markdown)

export_entries({
  format: "markdown",
});

Output:

# Memory Journal Export

Export Date: 2025-10-04
Total Entries: 54

---

## Entry #42 - 2025-10-04 16:45:30

**Type:** technical_achievement  
**Personal:** False  
**Tags:** performance, optimization, ml  
**Significance:** technical_breakthrough

Implemented lazy loading for ML dependencies - startup time improved from 14s to 2-3s!

**Context:**

- Repository: memory-journal-mcp
- Branch: main
- Commit: 5ee4651 - Add relationship visualization

---

## Entry #41 - 2025-10-04 14:20:15

...

Filtered Exports

By Date Range

export_entries({
  format: "markdown",
  start_date: "2025-10-01",
  end_date: "2025-10-31",
});

Use cases:

  • Monthly reports
  • Sprint summaries
  • Quarterly reviews

By Tags

export_entries({
  format: "json",
  tags: ["performance", "optimization"],
});

Use cases:

  • Topic-specific exports
  • Project documentation
  • Feature tracking

By Entry Type

export_entries({
  format: "markdown",
  entry_types: ["technical_achievement", "project_decision"],
});

Use cases:

  • Achievement reports
  • Performance reviews
  • Portfolio building

Combined Filters

export_entries({
  format: "markdown",
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  tags: ["sprint-15"],
  entry_types: ["technical_achievement", "project_decision"],
});

Use cases:

  • Sprint retrospectives
  • Filtered reports
  • Specific project documentation

Export Formats

JSON Format

Structure:

[
  {
    "id": integer,
    "entry_type": string,
    "content": string,
    "timestamp": string (ISO 8601),
    "is_personal": boolean,
    "tags": [string],
    "significance_type": string | null,
    "auto_context": object | null
  }
]

Benefits:

  • Machine-readable
  • Structured data
  • Easy to parse
  • Import to other tools

Use cases:

  • Data migration
  • Programmatic analysis
  • Integration with other tools
  • Backup with full fidelity

Markdown Format

Structure:

# Memory Journal Export

Export Date: YYYY-MM-DD
Total Entries: N

---

## Entry #ID - TIMESTAMP

**Type:** entry_type
**Personal:** True/False
**Tags:** tag1, tag2, tag3
**Significance:** significance_type

CONTENT

**Context:**

- Repository: repo_name
- Branch: branch_name
- Commit: hash - message

---

Benefits:

  • Human-readable
  • Beautiful formatting
  • Easy to share
  • Works in documentation

Use cases:

  • Reports
  • Documentation
  • Sharing with team
  • Blog posts
  • Portfolio

Use Cases

Monthly Report

export_entries({
  format: "markdown",
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  is_personal: false,
});

Save to file and share with team.

Sprint Retrospective

export_entries({
  format: "markdown",
  start_date: "2025-10-01",
  end_date: "2025-10-14",
  tags: ["sprint-15"],
});

Include in retrospective document.

Achievement Portfolio

export_entries({
  format: "markdown",
  entry_types: ["technical_achievement", "project_decision"],
  tags: ["significant"],
});

Use for performance reviews or portfolio.

Data Backup

export_entries({
  format: "json",
});

Save as journal-backup-2025-10-04.json

Migration to Another Tool

export_entries({
  format: "json",
});

Parse JSON and import to target system.

Saving Exports

Copy to Clipboard

  1. Run export tool
  2. Select all text
  3. Copy (Ctrl+C / Cmd+C)
  4. Paste into file

Save to File

Manually:

  1. Run export tool
  2. Copy output
  3. Create file (e.g., export.md)
  4. Paste and save

Script (future enhancement):

// Planned feature
export_entries({
  format: "markdown",
  output_file: "./exports/journal-2025-10.md",
});

JSON Schema

Complete JSON export schema:

interface JournalEntry {
  id: number;
  entry_type: string;
  content: string;
  timestamp: string; // ISO 8601
  is_personal: boolean;
  tags: string[];
  significance_type: string | null;
  auto_context: {
    repo_name?: string;
    repo_path?: string;
    branch?: string;
    last_commit?: {
      hash: string;
      message: string;
    };
    github_issues?: {
      count: number;
      recent_issues: Array<{
        number: number;
        title: string;
        state: string;
      }>;
    };
    cwd?: string;
    timestamp?: string;
  } | null;
}

type ExportData = JournalEntry[];

Markdown File Export (export_markdown)

Export journal entries as individual .md files with YAML frontmatter — ideal for archival, documentation systems, and Obsidian/Notion imports.

Parameters:

  • output_dir (required, string): Directory path to write .md files into. Note: This directory must be permitted by the ALLOWED_IO_ROOTS environment variable to prevent path traversal attacks.
  • start_date (optional, string): Start date filter (YYYY-MM-DD)
  • end_date (optional, string): End date filter (YYYY-MM-DD)
  • tags (optional, array): Filter by tags
  • entry_types (optional, array): Filter by entry types
  • limit (optional, integer): Maximum entries to export (default: 100)

Example:

export_markdown({
  output_dir: "/path/to/vault/journal",
  start_date: "2026-01-01",
  tags: ["milestone"],
});

Output per file (1-implemented-lazy-loading.md):

---
mj_id: 1
entry_type: technical_achievement
timestamp: 2026-04-08T12:00:00Z
source: memory-journal-mcp
tags:
  - milestone
  - performance
---

Implemented lazy loading for ML dependencies...

Note

Filenames are deterministic ({id}-{slug}.md) — re-exporting the same entries overwrites existing files without duplication.

Markdown File Import (import_markdown)

Import .md files with YAML frontmatter back into the journal — enabling full round-trip interoperability.

Parameters:

  • input_dir (required, string): Directory containing .md files to import. Note: This directory must be permitted by the ALLOWED_IO_ROOTS environment variable.
  • dry_run (optional, boolean): Preview what would be imported without writing (default: false)
  • overwrite (optional, boolean): Update existing entries matched by mj_id (default: false)

Example:

import_markdown({
  input_dir: "/path/to/vault/journal",
  dry_run: true, // Preview first
});

Import rules:

  • Files without mj_id frontmatter are created as new entries
  • Files with mj_id are matched to existing entries; skipped unless overwrite: true
  • Malformed frontmatter causes the file to be skipped (reported in skipped count)

Advanced Examples

Project Documentation

export_entries({
  format: "markdown",
  tags: ["memory-journal-mcp"],
  entry_types: [
    "project_decision",
    "technical_achievement",
    "feature_implementation",
  ],
});

Use in CHANGELOG.md or project wiki.

Personal Growth Journal

export_entries({
  format: "markdown",
  is_personal: true,
  start_date: "2025-01-01",
  end_date: "2025-12-31",
});

Annual reflection and growth tracking.

Feature Development History

export_entries({
  format: "markdown",
  tags: ["visualization", "mermaid"],
  start_date: "2025-09-01",
});

Document entire feature development timeline.

Best Practices

Regular Backups

Weekly backup:

export_entries({
  format: "json",
});

Save as: journal-backup-YYYY-MM-DD.json

Monthly Reports

End of month:

export_entries({
  format: "markdown",
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  is_personal: false,
});

Share with team or save for records.

Quarterly Reviews

Every 3 months:

export_entries({
  format: "markdown",
  start_date: "2025-07-01",
  end_date: "2025-09-30",
  entry_types: ["project_decision", "technical_achievement"],
});

Use for performance reviews.

Performance

Export Speed

Entries Format Time
100 JSON <100ms
100 Markdown <200ms
1,000 JSON <500ms
1,000 Markdown <1s
10,000 JSON <2s
10,000 Markdown <5s

Large Exports

For >1000 entries:

  • Use filters (date range, tags)
  • Export in batches
  • Use JSON (faster than Markdown)

Troubleshooting

Export Too Large

Problem: Output is overwhelming.

Solution:

// Add filters
export_entries({
  format: "markdown",
  start_date: "2025-10-01", // Limit time range
  tags: ["specific-project"], // Limit scope
});

Missing Entries

Check:

  • Date range is correct
  • Tags are spelled correctly
  • Entries aren't soft-deleted

Solution:

// Remove filters to see all
export_entries({
  format: "json",
});

Formatting Issues

JSON:

  • Valid JSON output
  • Can validate with jq or JSON validator

Markdown:

  • Standard Markdown syntax
  • Renders in GitHub, Obsidian, etc.

Integration Examples

GitHub Wiki

export_entries({
  format: "markdown",
  tags: ["memory-journal-mcp"],
  start_date: "2025-10-01",
});

Copy to wiki page for project documentation.

Blog Post

export_entries({
  format: "markdown",
  entry_types: ["technical_achievement"],
  tags: ["optimization", "performance"],
});

Edit and publish as blog post.

Notion / Obsidian

export_entries({
  format: "markdown",
});

Import into note-taking tool.

Data Analysis

export_entries({
  format: "json",
});

Parse with JavaScript for analysis:

import { readFileSync } from "fs";

const data = JSON.parse(readFileSync("export.json", "utf-8"));
const typeCounts = data.reduce((acc, entry) => {
  acc[entry.entry_type] = (acc[entry.entry_type] || 0) + 1;
  return acc;
}, {});
console.log(typeCounts);

Future Enhancements

Planned features:

  1. Direct file output (in-response)

    export_entries({ output_file: "./export.md" });

  2. Custom templates

    export_entries({ template: "sprint-retro" });

  3. Multiple formats

    • HTML
    • PDF
    • CSV

  4. Scheduled exports

    • Automatic weekly backups
    • Email reports

Next: Check Examples or Tools Reference.

🏠 Home

Getting Started

Core Features

Knowledge Graph

GitHub Integration

Workflows

Deployment

Architecture

Clone this wiki locally