README

🧠 memhelper 🧠

Markdown-first memory layer for LLM agents. Exposes a grab(query) MCP tool that returns the curated facts most relevant to a natural-language question. A separate supervisor worker handles all writes — refreshing the search index across every configured input source, distilling new sources via an LLM, and periodically compacting duplicates and obsolete entries. Memory entries are plain .md files with a tiny YAML frontmatter — readable, editable, git-versionable. Cross-references between entries are written as [[slug]] wiki-links and followed one hop at retrieval time, so a single query surfaces related neighbours automatically.

installation

composer require vielhuber/memhelper

ai:
    provider: openai
    model: gpt-5
    api_key: sk-...

output: /path/to/memory

input_files:
    - /path/to/external/docs
    - /path/to/external/notes

input_dbs:
    - driver: sqlite
      path: /path/to/database.db
      include_tables: [chats_messages] # optional

    - driver: mysql
      host: 127.0.0.1
      port: 3306
      user: root
      password:
      database: memhelper
      exclude_tables: [analytics_events] # optional

    - driver: postgres
      host: 127.0.0.1
      port: 5432
      user: root
      password:
      database: database

usage

library

use vielhuber\memhelper\memhelper;

$memory = new memhelper(
    configPath: '/path/to/config.yaml',
    logPath: '/var/log/memory.log'
);

$facts = $memory->grab(
    query: 'how is the user\'s dog named?',
    limit: 10
);
// → [['slug' => 'pet-roger', 'tags' => ['pet', 'dog'], 'description' => '...',
//     'body' => '...', 'sources' => ['dbrow:…'], 'score' => -3.41, 'via' => null], ...]

worker

[program:memhelper-worker]
command=php /app/vendor/vielhuber/memhelper/bin/memhelper-worker /path/to/memory.yaml /var/log/memory.log
autostart=true
autorestart=true

tests

./vendor/bin/phpunit

mcp

{
    "mcpServers": {
        "memory": {
            "command": "php",
            "args": ["./vendor/bin/mcp-server.php"],
            "env": {
                "MEMHELPER_CONFIG": "/path/to/memory.yaml",
                "MEMHELPER_LOG": "/var/log/memory.log"
            }
        }
    }
}