Memoria Client

A JavaScript client for interacting with the Memoria digital memory management library via its Flask-based REST API. This npm package allows Node.js applications to capture, search, and replay digital memories, leveraging Memoria's local-first, privacy-focused features.

Features

• Add Memories: Store text-based memories (e.g., notes, emails, chats) with timestamps and sources.
• Semantic Search: Query memories using natural language (e.g., "Find EV flywheels PDF").
• Timeline Playback: Retrieve and replay activities in a chronological timeline.
• Advanced AI:
  • Generate insights (summaries) using local models or cloud APIs (Gemini, OpenAI, Anthropic, Perplexity, Grok).
  • Answer questions based on memory context.
  • Cluster memories into topics.
  • Analyze sentiment and provide context-aware recommendations.
• Export: Save memories to JSON or Notion.
• Privacy: Local processing by default; warnings issued for cloud API usage.

Installation

1. Install the package:

npm install memoria-client


Ensure the Memoria Flask server is running:


Clone the Memoria repository: git clone <repo_url>
Navigate to memoria-tool and install Python dependencies: 

pip install -r requirements.txt
or
python -m pip install -r requirements.txt

cd memoria-tool
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install .[cloud]


Set an encryption key:

export MEMORIA_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")


Start the server:

python server/app.py

API Setup
For cloud features (optional), set API keys as environment variables or pass explicitly:

Gemini: Get key from ai.google.dev.export GEMINI_API_KEY=your_key


OpenAI: Get key from platform.openai.com.export OPENAI_API_KEY=your_key


Anthropic: Get key from console.anthropic.com.export ANTHROPIC_API_KEY=your_key


Perplexity: Get key from api.perplexity.ai.export PERPLEXITY_API_KEY=your_key


Grok: Get key from x.ai/api.export XAI_API_KEY=your_key


Gmail/Slack/Notion: See Memoria's main README for setup.

Usage
const MemoriaClient = require('memoria-client');

const client = new MemoriaClient('http://localhost:5000');

async function main() {
    try {
        // Add a memory
        await client.addMemory('Meeting at 3 PM about EV flywheels', new Date().toISOString(), 'manual');

        // Search memories
        const results = await client.search('EV flywheels');
        console.log('Search Results:', results.data);

        // Get timeline playback
        const start = new Date(Date.now() - 24*60*60*1000).toISOString();
        const end = new Date().toISOString();
        const playback = await client.getPlayback(start, end);
        console.log('Playback:', playback.data);

        // Generate insight (cloud example)
        const insight = await client.getInsight(playback.data, 'gemini', 'your_gemini_key', 'gemini-1.5-pro');
        console.log('Insight:', insight.data);

        // Question answering
        const answer = await client.questionAnswering('When is the meeting?', playback.data[0].content, 'local');
        console.log('Answer:', answer.data);

        // Topic modeling
        const texts = playback.data.map(e => e.content);
        const clusters = await client.topicModeling(texts, 'openai', 'your_openai_key');
        console.log('Clusters:', clusters.data);

        // Export to Notion
        await client.exportToNotion('your_notion_token', 'your_parent_page_id');
    } catch (error) {
        console.error('Error:', error.message);
    }
}

main();

API Reference

MemoriaClient(baseUrl): Initialize with Flask server URL (default: http://localhost:5000).
addMemory(content, timestamp, source): Add a memory.
search(query, topK): Search memories with natural language.
getPlayback(startTime, endTime): Get chronological events.
getInsight(events, provider, apiKey, model): Generate summary (local or cloud).
questionAnswering(question, context, provider, apiKey, model): Answer questions.
topicModeling(texts, provider, apiKey, model): Cluster texts into topics.
getRecommendation(memories, provider, apiKey, model): Suggest actions.
exportToJson(filepath): Export memories to JSON.
exportToNotion(token, parentPageId): Export to Notion.

Privacy and Security

Local-First: The Memoria backend stores data locally with AES encryption.
Cloud Warnings: Cloud API calls (e.g., Gemini) trigger warnings about data leaving the device.
Secure Setup: Use environment variables for API keys and MEMORIA_KEY.

Extensibility
Add custom endpoints to the Flask server (server/app.py) and methods to MemoriaClient. Example:
async ingestTelegram(token, chatId) {
    return this.api.post('/ingest_telegram', { token, chat_id: chatId });
}

Requirements

Node.js 14+.
Memoria Flask server running (python server/app.py).
Optional: Cloud API keys for advanced features.

License
MIT License. See LICENSE file in the Memoria repository.
Notes

Ensure the Flask server is running before using the client.