🏛️ LLMemory-Palace

📦 npm | 💻 GitHub | 📖 Docs | 🗺️ Roadmap | 🐛 Issues

---

The Problem

You're working with Claude or ChatGPT. You paste your codebase files one by one. The context fills up. The AI forgets what it saw first. You explain again. Context overflows. You start over.

The Solution

LLMemory-Palace maps your code into a portable format. Not your actual code—a structural map. Patterns, flows, fingerprints. One string replaces dozens of file pastes.

Install

npm install llmemory-palace
# or
bun add llmemory-palace

Node.js 18+ | Bun 1.0+

Quick Start

npx palace init
npx palace scan
npx palace genome

Commands

Command	Description
init	Create .palace/ directory
scan	Analyze codebase structure
genome	Generate genome string
export	Export to CXML/JSON/YAML/MessagePack
rebuild	Reconstruct from genome
pack	Create portable package
merge	Merge package into project
refresh	Incremental update with --ripple for dependents
patterns	View detected patterns
flows	View behavior graphs
deps	Analyze dependencies
status	Show current state
query	Interactive LLM query
validate	Security check genome

Options

--output, -o      Output file/directory
--format, -f      cxml | json | yaml | msgpack | genome
--level, -l       Compression 1-4 (default: 3)
--ripple, -r      Update dependents (refresh command)
--dry-run, -d     Preview without changes
--metrics, -m     Show before/after metrics

Security

• No eval()
• Input validation
• Path traversal protection
• Injection protection
• Safe genome parsing (JSON only)
• 28 security tests passing

API

import { Palace } from 'llmemory-palace';

const palace = new Palace({ projectPath: './my-project' });
await palace.init();
await palace.scan();
const genome = await palace.generateGenome();
console.log(genome);

Documentation

• Palace API
• Pattern Library
• Behavior Graph
• Semantic Hash
• Genome Format
• CLI Validator
• Safe Parser

Export Formats

• CXML (default) - Compressed, token-efficient
• JSON - Human-readable
• YAML - Configuration-friendly
• MessagePack - Binary serialization

Token Efficiency

Reference-based output saves 90%+ tokens:

• palace:// URIs for on-demand resolution
• Compressed genomes: ~20KB for large projects
• Incremental scans with LRU caching

MCP Server

90%+ token savings with reference-based minimal context:

// ~/.claude.json
{
  "mcpServers": {
    "palace": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "llmemory-palace", "mcp"]
    }
  }
}

Tools:

• mcp__palace__init - Initialize project
• mcp__palace__scan - Scan with reference output (97% token savings)
• mcp__palace__genome - Generate compressed genome (99% savings)
• mcp__palace__resolve_ref - Resolve palace:// URIs at depth 1-3
• mcp__palace__status - Check project status

Token Savings:

Operation	Full	Reference	Savings
scan	5000	150	97%
genome	20000	200	99%

Performance

• LRU cache for faster rescans
• Worker threads for parallel scanning
• Chunked processing for files >100MB

Plugin System

import { HookSystem } from 'llmemory-palace/plugins';
hooks.on('scan', async (result) => { /* ... */ }, { priority: 10 });

Large Files

import { LargeFileHandler } from 'llmemory-palace/streaming';
const handler = new LargeFileHandler({ chunkSize: 1024 * 1024 });
handler.exportChunked(data, 'output');

AI Integration

import { PromptTemplates } from 'llmemory-palace/ai/prompts';
const prompts = new PromptTemplates(palace);
prompts.formatForLLM('claude', query);

License

MIT