@alsania-io/scribe

Markdown-based audit logging with redaction for Alsania ecosystem

Features

• 📝 Markdown-based logs — Human-readable, version-control friendly
• 🔒 Automatic redaction — Sensitive fields (API keys, passwords, tokens) are redacted
• 📅 Session-based organization — Logs organized by date and session
• 🔗 Anchoring support — SHA3-256 hashing for on-chain verification
• 🎨 Configurable templates — Customizable header and entry formats
• 🚀 Zero dependencies — Pure TypeScript, no external dependencies

Installation

npm install @alsania-io/scribe

Quick Start

import { Scribe } from '@alsania-io/scribe';

const scribe = new Scribe({
  root: './logs',
  redact: ['Authorization', 'api_key', 'password']
});

// Start a session
scribe.session('session-123', {
  owner: 'Sigma',
  model: 'echo-cloud',
  mcpUrl: 'http://localhost:8050/mcp'
});

// Log different types of entries
scribe.prompt('What is the meaning of life?');
scribe.response('The meaning of life is 42.');
scribe.toolCall('calculator', { expression: '2 + 2' }, 4);
scribe.error('Something went wrong');
scribe.event('connection_established', { peer: 'Aegis' });

// Get the latest log file
const latest = scribe.getLatestLog();
console.log(`Log file: ${latest}`);

// Anchor the log (for on-chain verification)
const anchor = scribe.anchorLatest();
console.log(`Hash: ${anchor.hash}`);

// Get all anchors
const anchors = scribe.getAnchors();
console.log(anchors);

Configuration

const config = {
  // Root directory for logs
  root: './logs',
  
  // Log format (only 'markdown' for now)
  mode: 'markdown',
  
  // Automatically log tokens and patches
  autoLogTokens: true,
  autoLogPatches: true,
  
  // Fields to redact
  redact: ['Authorization', 'api_key', 'password', 'secret'],
  
  // Header template for new sessions
  headerTemplate: `# Scribe — {{date}} ({{session}})
  
**Owner:** {{owner}}
**Model:** {{model}}
**MCP:** {{mcp}}

---`,
  
  // Entry template
  entryTemplate: `## {{time}} — {{type}}
  
{{content}}
`
};

API

new Scribe(config?)

Create a new Scribe instance.

scribe.session(id, context?)

Start a new session. All subsequent logs will be written to this session.

scribe.prompt(content, metadata?)

Log a user prompt.

scribe.response(content, metadata?)

Log an AI response.

scribe.toolCall(toolName, args, result?)

Log a tool call with arguments and result.

scribe.error(message, stack?, metadata?)

Log an error with optional stack trace.

scribe.event(name, data?)

Log a custom event.

scribe.write(entry)

Write a raw entry.

scribe.getLatestLog()

Get the path to the latest log file.

scribe.hashLog(filePath)

Compute SHA3-256 hash of a log file.

scribe.anchorLatest()

Anchor the latest log file (creates an anchor record).

scribe.getAnchors()

Get all anchor records.

Integration with Alsania Projects

AlsaniaMCP

import { Scribe } from '@alsania-io/scribe';

const scribe = new Scribe({ root: '/var/log/alsaniamcp' });
scribe.session(serverId, { owner: 'Sigma', model: 'echo-cloud' });

DevConX

import { Scribe } from '@alsania-io/scribe';

const scribe = new Scribe({ root: '~/.devcon/logs' });
scribe.session(extensionSession, { owner: 'Sigma' });

Nyx

import { Scribe } from '@alsania-io/scribe';

const scribe = new Scribe({ root: '~/.nyx/logs' });
scribe.session(browserSession, { owner: 'Sigma' });

License

MIT