--- name: fsxmemory version: 1.3.1 description: Structured memory system for AI agents. Context death resilience (checkpoint/recover), structured storage, Obsidian-compatible markdown, and local semantic search. author: Foresigxt repository: https://github.com/Foresigxt/foresigxt-cli-memory ---

Foresigxt Memory

Structured memory system for AI agents.

Install

npm install -g @foresigxt/foresigxt-cli-memory

Setup

Option 1: Initialize New Vault

# Initialize vault (creates folder structure + templates)
fsxmemory init ~/memory

Option 2: Use Existing Vault

For isolated workspace memory (each workspace has its own vault):

# Create .env in workspace root
echo 'FSXMEMORY_PATH=/path/to/workspace/memory' > .env

# All agents in THIS workspace use this isolated vault
fsxmemory stats  # Works automatically!

For shared memory across all workspaces:

# Set global environment variable (in ~/.bashrc or ~/.zshrc)
export FSXMEMORY_PATH=/path/to/shared/memory

# All agents in ALL workspaces share the same vault

Or: Use --vault flag for one-time override:

fsxmemory stats --vault /path/to/other/vault

Core Commands

Store memories by type

# Types: fact, feeling, decision, lesson, commitment, preference, relationship, project, procedural, semantic, episodic
fsxmemory remember decision "Use Postgres over SQLite" --content "Need concurrent writes for multi-agent setup"
fsxmemory remember lesson "Context death is survivable" --content "Checkpoint before heavy work"
fsxmemory remember relationship "Justin Dukes" --content "Client contact at Hale Pet Door"
fsxmemory remember procedural "Deploy to Production" --content "1. Run tests 2. Build 3. Deploy"
fsxmemory remember semantic "Event Loop Concept" --content "JavaScript's concurrency model..."
fsxmemory remember episodic "First Production Deploy" --content "Deployed v2.0 today, team was nervous but it went well"

Quick capture to inbox

fsxmemory capture "TODO: Review PR tomorrow"

Search (requires qmd installed)

# Keyword search (fast)
fsxmemory search "client contacts"

# Semantic search (slower, more accurate)
fsxmemory vsearch "what did we decide about the database"

Context Death Resilience

Checkpoint (save state frequently)

fsxmemory checkpoint --working-on "PR review" --focus "type guards" --blocked "waiting for CI"

Recover (check on wake)

fsxmemory recover --clear
# Shows: death time, last checkpoint, recent handoff

Handoff (before session end)

fsxmemory handoff \
  --working-on "Foresigxt Memory improvements" \
  --blocked "npm token" \
  --next "publish to npm, create skill" \
  --feeling "productive"

Recap (bootstrap new session)

fsxmemory recap
# Shows: recent handoffs, active projects, pending commitments, lessons

Migration from Other Formats

Migrate existing vaults from OpenClaw, Obsidian, or other markdown-based systems:

Analyze First (Dry Run)

# See what would be changed without modifying files
fsxmemory migrate --from openclaw --vault /path/to/vault --dry-run

Migrate with Backup

# Recommended: Creates automatic backup before migration
fsxmemory migrate --from openclaw --vault /path/to/vault --backup

# The migration:
# ✅ Adds YAML frontmatter to all markdown files
# ✅ Renames directories (procedural→procedures, semantic→knowledge, episodic→episodes)
# ✅ Creates .fsxmemory.json config file
# ✅ Preserves all content and custom categories
# ✅ Creates timestamped backup for rollback

Rollback if Needed

# Restore from backup if something went wrong
fsxmemory migrate --rollback --vault /path/to/vault

Migration Options

# Available source formats
--from openclaw      # OpenClaw vault format
--from obsidian      # Obsidian vault format
--from generic       # Generic markdown vault

# Migration flags
--dry-run           # Preview changes without modifying files
--backup            # Create backup before migration (recommended)
--force             # Skip confirmation prompts
--verbose           # Show detailed progress
--rollback          # Restore from last backup

Example: Migrate OpenClaw Vault

# 1. Analyze first
fsxmemory migrate --from openclaw --vault ~/.openclaw/workspace/memory --dry-run

# 2. Run migration with backup
fsxmemory migrate --from openclaw --vault ~/.openclaw/workspace/memory --backup --verbose

# 3. Verify migration worked
fsxmemory stats --vault ~/.openclaw/workspace/memory
fsxmemory doctor --vault ~/.openclaw/workspace/memory

Migration Speed: ~53 files in 0.07 seconds ⚡

Auto-linking

Wiki-link entity mentions in markdown files:

# Link all files
fsxmemory link --all

# Link single file
fsxmemory link memory/2024-01-15.md

Templates Reference

Foresigxt Memory includes structured templates for consistent documentation. Location: templates/ directory.

Available Templates

| Template | Type | Use For | Sections | |----------|------|---------|----------| | decision.md | decision | Key choices, architecture decisions | Context, Options, Decision, Outcome | | procedure.md | procedural | How-to guides, workflows, SOPs | Purpose, Prerequisites, Steps, Pitfalls, Verification | | knowledge.md | semantic | Concepts, definitions, mental models | Definition, Key Concepts, Examples, Why It Matters | | episode.md | episodic | Events, experiences, meetings | What Happened, Context, Key Moments, Reflection | | person.md | person | Contacts, relationships | Contact, Role, Working With, Interactions | | project.md | project | Active work, initiatives | Goal, Status, Next Actions, Blockers | | lesson.md | lesson | Insights, patterns learned | Situation, Lesson, Application | | handoff.md | handoff | Session continuity | Working On, Context, Next Steps, Blockers | | daily.md | daily | Daily notes, journal | Focus, Done, Notes |

Template Usage

Templates are automatically selected by memory type:

fsxmemory remember decision "Title" --content "..."    # → templates/decision.md
fsxmemory remember procedural "Title" --content "..."  # → templates/procedure.md
fsxmemory remember semantic "Title" --content "..."    # → templates/knowledge.md
fsxmemory remember episodic "Title" --content "..."    # → templates/episode.md
fsxmemory remember relationship "Name" --content "..." # → templates/person.md
fsxmemory remember lesson "Title" --content "..."      # → templates/lesson.md

To view template structure: Read the template file in templates/ directory before creating a memory document.

Template features:

• YAML frontmatter with metadata (title, date, type, status)
• Structured sections with placeholder guidance
• Wiki-link suggestions for connections
• Auto-generated tags

Folder Structure

vault/
├── .fsxmemory/           # Internal state
│   ├── last-checkpoint.json
│   └── dirty-death.flag
├── decisions/            # Key choices with reasoning
├── lessons/              # Insights and patterns
├── people/               # One file per person
├── projects/             # Active work tracking
├── procedures/           # How-to guides and workflows
├── knowledge/            # Concepts and definitions
├── episodes/             # Personal experiences
├── handoffs/             # Session continuity
├── inbox/                # Quick captures
└── templates/            # Document templates (9 types)

Best Practices

1. Checkpoint every 10-15 min during heavy work
2. Handoff before session end — future you will thank you
3. Recover on wake — check if last session died
4. Use types — knowing WHAT you're storing helps WHERE to put it
5. Wiki-link liberally — [[person-name]] builds your knowledge graph

Integration with qmd

Foresigxt Memory uses qmd for search:

...