tx memory

tx memory source add <dir> [options]

# Register a notes directory
tx memory source add ~/notes

# Register with a label
tx memory source add ./docs --label "Project Docs"

# Register and output JSON
tx memory source add ~/wiki --json

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

// Register a directory
const source = await tx.memory.sourceAdd('/Users/me/notes')
// Returns: { id, rootDir, label, createdAt }

// Register with a label
const docs = await tx.memory.sourceAdd('./docs', 'Project Docs')
console.log(`Registered: ${docs.rootDir} (${docs.label})`)

{
  "tool": "tx_memory_source_add",
  "arguments": {
    "dir": "/Users/me/notes",
    "label": "Project Notes"
  }
}

POST /api/memory/sources
Content-Type: application/json

{
  "dir": "/Users/me/notes",
  "label": "Project Notes"
}

curl -X POST http://localhost:3456/api/memory/sources \
  -H "Content-Type: application/json" \
  -d '{"dir": "/Users/me/notes", "label": "Project Notes"}'

tx memory source rm <dir> [options]

# Remove a source
tx memory source rm ~/old-notes

# Remove with JSON output
tx memory source rm ./archive --json

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

await tx.memory.sourceRemove('/Users/me/old-notes')

{
  "tool": "tx_memory_source_rm",
  "arguments": {
    "dir": "/Users/me/old-notes"
  }
}

DELETE /api/memory/sources
Content-Type: application/json

{
  "dir": "/Users/me/old-notes"
}

curl -X DELETE http://localhost:3456/api/memory/sources \
  -H "Content-Type: application/json" \
  -d '{"dir": "/Users/me/old-notes"}'

tx memory source list [options]

# List all sources
tx memory source list

# JSON output
tx memory source list --json

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

const sources = await tx.memory.sourceList()
// Returns: Array<{ id, rootDir, label, createdAt }>

for (const src of sources) {
  console.log(`${src.rootDir} (${src.label ?? 'no label'})`)
}

{
  "tool": "tx_memory_source_list",
  "arguments": {}
}

GET /api/memory/sources

curl http://localhost:3456/api/memory/sources

tx memory add <title> [options]

# Create a simple document
tx memory add "Meeting Notes 2024-01-15"

# Create with content and tags
tx memory add "Auth Architecture" \
  -c "## Overview\nJWT-based authentication with refresh tokens." \
  -t architecture auth

# Create with properties and target directory
tx memory add "Sprint Retro" \
  --prop sprint=42 --prop team=backend \
  -d ~/notes/retros

# Create and output JSON
tx memory add "API Design" -t api design --json

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

const doc = await tx.memory.add({
  title: 'Auth Architecture',
  content: '## Overview\nJWT-based authentication with refresh tokens.',
  tags: ['architecture', 'auth'],
  properties: { status: 'draft', sprint: '42' },
  dir: '/Users/me/notes',
})
// Returns: { id, filePath, rootDir, title, content, tags, ... }

console.log(`Created: ${doc.id} at ${doc.filePath}`)

{
  "tool": "tx_memory_add",
  "arguments": {
    "title": "Auth Architecture",
    "content": "## Overview\nJWT-based authentication with refresh tokens.",
    "tags": ["architecture", "auth"],
    "properties": { "status": "draft" },
    "dir": "/Users/me/notes"
  }
}

POST /api/memory/documents
Content-Type: application/json

{
  "title": "Auth Architecture",
  "content": "## Overview\nJWT-based authentication with refresh tokens.",
  "tags": ["architecture", "auth"],
  "properties": { "status": "draft" }
}

curl -X POST http://localhost:3456/api/memory/documents \
  -H "Content-Type: application/json" \
  -d '{"title": "Auth Architecture", "tags": ["architecture", "auth"]}'

tx memory show <id> [options]

# Show a document
tx memory show mem-a1b2c3d4e5f6

# Show as JSON
tx memory show mem-a1b2c3d4e5f6 --json

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

const doc = await tx.memory.show('mem-a1b2c3d4e5f6')
// Returns: { id, filePath, rootDir, title, content, tags, frontmatter, ... }

console.log(doc.title)
console.log(doc.content)

{
  "tool": "tx_memory_show",
  "arguments": {
    "id": "mem-a1b2c3d4e5f6"
  }
}

GET /api/memory/documents/:id

curl http://localhost:3456/api/memory/documents/mem-a1b2c3d4e5f6

tx memory list [options]

# List all documents
tx memory list

# Filter by source
tx memory list --source ~/notes

# Filter by tags
tx memory list -t architecture design

# Combined filters with JSON
tx memory list --source ./docs -t api --json

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

// List all documents
const docs = await tx.memory.list()

// Filter by source and tags
const filtered = await tx.memory.list({
  source: '/Users/me/notes',
  tags: ['architecture'],
})
// Returns: Array<{ id, filePath, rootDir, title, content, tags, ... }>

for (const doc of filtered) {
  console.log(`${doc.id}: ${doc.title}`)
}

{
  "tool": "tx_memory_list",
  "arguments": {
    "source": "/Users/me/notes",
    "tags": ["architecture"]
  }
}

GET /api/memory/documents?source=/Users/me/notes&tags=architecture,auth

# List all documents
curl http://localhost:3456/api/memory/documents

# Filter by source and tags
curl "http://localhost:3456/api/memory/documents?source=/Users/me/notes&tags=architecture"

tx memory search <query> [options]

# Basic keyword search
tx memory search "authentication flow"

# Semantic similarity search
tx memory search "how does login work" --semantic

# Keyword search with graph expansion
tx memory search "database schema" --expand

# Combined: keyword + semantic + graph expansion
tx memory search "error handling patterns" --semantic --expand

# Filter by tags and properties
tx memory search "deployment" -t devops --prop env=production

# Limit results and set minimum score
tx memory search "react hooks" -n 5 --min-score 0.5

# JSON output for scripting
tx memory search "API design" --json

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

// Basic keyword search
const results = await tx.memory.search({ query: 'authentication flow' })

// Combined: semantic + graph expansion with filters
const expanded = await tx.memory.search({
  query: 'error handling patterns',
  semantic: true,
  expand: true,
  limit: 5,
  minScore: 0.3,
  tags: ['backend'],
  props: { env: 'production' },
})
// Returns: Array<{ id, title, content, relevanceScore, bm25Score, vectorScore, ... }>

for (const doc of expanded) {
  console.log(`[${doc.relevanceScore.toFixed(2)}] ${doc.title}`)
}

{
  "tool": "tx_memory_search",
  "arguments": {
    "query": "authentication flow",
    "semantic": true,
    "expand": true,
    "limit": 5,
    "tags": ["backend"]
  }
}

GET /api/memory/search?query=authentication+flow&semantic=true&expand=true&limit=5

# Basic keyword search
curl "http://localhost:3456/api/memory/search?query=authentication+flow"

# Combined search with filters
curl "http://localhost:3456/api/memory/search?query=error+handling&semantic=true&expand=true&limit=5&tags=backend"

tx memory index [options]

# Full re-index
tx memory index

# Incremental index (skip unchanged files)
tx memory index --incremental

# Check indexing status
tx memory index --status

# Incremental with JSON output
tx memory index -i --json

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

// Full re-index
const result = await tx.memory.index()
// Returns: { indexed, skipped, removed }

console.log(`Indexed: ${result.indexed}, Skipped: ${result.skipped}`)

// Incremental index (only changed files)
const incremental = await tx.memory.index({ incremental: true })

// Check indexing status
const status = await tx.memory.indexStatus()
// Returns: { totalFiles, indexed, stale, embedded, links, sources }

{
  "tool": "tx_memory_index",
  "arguments": {
    "incremental": true
  }
}

{
  "tool": "tx_memory_index_status",
  "arguments": {}
}

POST /api/memory/index
Content-Type: application/json

{
  "incremental": true
}

# Full re-index
curl -X POST http://localhost:3456/api/memory/index

# Incremental index
curl -X POST http://localhost:3456/api/memory/index \
  -H "Content-Type: application/json" \
  -d '{"incremental": true}'

# Check indexing status
curl http://localhost:3456/api/memory/index/status

tx memory tag <id> <tags...>

# Add a single tag
tx memory tag mem-a1b2c3d4e5f6 architecture

# Add multiple tags
tx memory tag mem-a1b2c3d4e5f6 backend api v2

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

await tx.memory.tag('mem-a1b2c3d4e5f6', ['backend', 'api', 'v2'])

{
  "tool": "tx_memory_tag",
  "arguments": {
    "id": "mem-a1b2c3d4e5f6",
    "tags": ["backend", "api", "v2"]
  }
}

POST /api/memory/documents/:id/tags
Content-Type: application/json

{
  "tags": ["backend", "api", "v2"]
}

curl -X POST http://localhost:3456/api/memory/documents/mem-a1b2c3d4e5f6/tags \
  -H "Content-Type: application/json" \
  -d '{"tags": ["backend", "api", "v2"]}'

tx memory untag <id> <tags...>

# Remove a single tag
tx memory untag mem-a1b2c3d4e5f6 draft

# Remove multiple tags
tx memory untag mem-a1b2c3d4e5f6 wip experimental

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

await tx.memory.untag('mem-a1b2c3d4e5f6', ['wip', 'experimental'])

{
  "tool": "tx_memory_untag",
  "arguments": {
    "id": "mem-a1b2c3d4e5f6",
    "tags": ["wip", "experimental"]
  }
}

DELETE /api/memory/documents/:id/tags
Content-Type: application/json

{
  "tags": ["wip", "experimental"]
}

curl -X DELETE http://localhost:3456/api/memory/documents/mem-a1b2c3d4e5f6/tags \
  -H "Content-Type: application/json" \
  -d '{"tags": ["wip", "experimental"]}'

tx memory set <id> <key> <value>

# Set a string property
tx memory set mem-a1b2c3d4e5f6 status "reviewed"

# Set a numeric property
tx memory set mem-a1b2c3d4e5f6 priority 1

# Set a custom property
tx memory set mem-a1b2c3d4e5f6 owner "team-backend"

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

await tx.memory.set('mem-a1b2c3d4e5f6', 'status', 'reviewed')
await tx.memory.set('mem-a1b2c3d4e5f6', 'owner', 'team-backend')

{
  "tool": "tx_memory_set",
  "arguments": {
    "id": "mem-a1b2c3d4e5f6",
    "key": "status",
    "value": "reviewed"
  }
}

PUT /api/memory/documents/:id/props/:key
Content-Type: application/json

{
  "value": "reviewed"
}

curl -X PUT http://localhost:3456/api/memory/documents/mem-a1b2c3d4e5f6/props/status \
  -H "Content-Type: application/json" \
  -d '{"value": "reviewed"}'

tx memory unset <id> <key>

# Remove a property
tx memory unset mem-a1b2c3d4e5f6 status

# Remove a custom property
tx memory unset mem-a1b2c3d4e5f6 owner

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

await tx.memory.unset('mem-a1b2c3d4e5f6', 'status')

{
  "tool": "tx_memory_unset",
  "arguments": {
    "id": "mem-a1b2c3d4e5f6",
    "key": "status"
  }
}

DELETE /api/memory/documents/:id/props/:key

curl -X DELETE http://localhost:3456/api/memory/documents/mem-a1b2c3d4e5f6/props/status

tx memory props <id>

tx memory props mem-a1b2c3d4e5f6

Properties for mem-a1b2c3d4e5f6 (auth-architecture.md):

  tags:     architecture, auth
  created:  2024-01-15T10:30:00Z
  status:   reviewed
  owner:    team-backend
  related:  login-flow.md, token-refresh.md

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

const props = await tx.memory.props('mem-a1b2c3d4e5f6')
// Returns: Record<string, string>

for (const [key, value] of Object.entries(props)) {
  console.log(`${key}: ${value}`)
}

{
  "tool": "tx_memory_props",
  "arguments": {
    "id": "mem-a1b2c3d4e5f6"
  }
}

GET /api/memory/documents/:id/props

curl http://localhost:3456/api/memory/documents/mem-a1b2c3d4e5f6/props

tx memory relate <id> <target>

# Relate two documents
tx memory relate mem-a1b2c3d4e5f6 mem-f6e5d4c3b2a1

# Relate by filename
tx memory relate mem-a1b2c3d4e5f6 login-flow.md

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

await tx.memory.relate('mem-a1b2c3d4e5f6', 'mem-f6e5d4c3b2a1')

// Or relate by filename
await tx.memory.relate('mem-a1b2c3d4e5f6', 'login-flow.md')

{
  "tool": "tx_memory_relate",
  "arguments": {
    "id": "mem-a1b2c3d4e5f6",
    "target": "login-flow.md"
  }
}

POST /api/memory/documents/:id/relate
Content-Type: application/json

{
  "target": "login-flow.md"
}

curl -X POST http://localhost:3456/api/memory/documents/mem-a1b2c3d4e5f6/relate \
  -H "Content-Type: application/json" \
  -d '{"target": "login-flow.md"}'

tx memory links <id>

tx memory links mem-a1b2c3d4e5f6

Outgoing links from auth-architecture.md:

  [wikilink]    → login-flow.md
  [wikilink]    → token-refresh.md
  [frontmatter] → security-review.md
  [explicit]    → oauth2-spec.md

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

const links = await tx.memory.links('mem-a1b2c3d4e5f6')
// Returns: Array<{ id, sourceDocId, targetDocId, targetRef, linkType, createdAt }>

for (const link of links) {
  console.log(`[${link.linkType}] → ${link.targetRef}`)
}

{
  "tool": "tx_memory_links",
  "arguments": {
    "id": "mem-a1b2c3d4e5f6"
  }
}

GET /api/memory/documents/:id/links

curl http://localhost:3456/api/memory/documents/mem-a1b2c3d4e5f6/links

tx memory backlinks <id>

tx memory backlinks mem-a1b2c3d4e5f6

Incoming links to auth-architecture.md:

  [wikilink]    ← api-design.md
  [frontmatter] ← security-overview.md
  [explicit]    ← onboarding-guide.md

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

const backlinks = await tx.memory.backlinks('mem-a1b2c3d4e5f6')
// Returns: Array<{ id, sourceDocId, targetDocId, targetRef, linkType, createdAt }>

for (const link of backlinks) {
  console.log(`[${link.linkType}] <- ${link.sourceDocId}`)
}

{
  "tool": "tx_memory_backlinks",
  "arguments": {
    "id": "mem-a1b2c3d4e5f6"
  }
}

GET /api/memory/documents/:id/backlinks

curl http://localhost:3456/api/memory/documents/mem-a1b2c3d4e5f6/backlinks

tx memory link <source-id> <target-ref>

# Link by memory ID
tx memory link mem-a1b2c3d4e5f6 mem-f6e5d4c3b2a1

# Link by filename reference
tx memory link mem-a1b2c3d4e5f6 deployment-guide.md

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ apiUrl: 'http://localhost:3456' })

await tx.memory.link('mem-a1b2c3d4e5f6', 'mem-f6e5d4c3b2a1')

// Or link by filename
await tx.memory.link('mem-a1b2c3d4e5f6', 'deployment-guide.md')

{
  "tool": "tx_memory_link",
  "arguments": {
    "sourceId": "mem-a1b2c3d4e5f6",
    "targetRef": "deployment-guide.md"
  }
}

POST /api/memory/links
Content-Type: application/json

{
  "sourceId": "mem-a1b2c3d4e5f6",
  "targetRef": "deployment-guide.md"
}

curl -X POST http://localhost:3456/api/memory/links \
  -H "Content-Type: application/json" \
  -d '{"sourceId": "mem-a1b2c3d4e5f6", "targetRef": "deployment-guide.md"}'