DEV Community: Mohamed Ashraf Elsaed

Aletheia 0.1.13: start the MCP server from npm, and a fix for the MCP Registry entry

Mohamed Ashraf Elsaed — Tue, 03 Nov 2026 01:56:40 +0000

Aletheia (npm: aletheia-mem) is a free, local memory and rules hub for AI coding tools. Each coding agent forgets between sessions and keeps its own rules file. Aletheia keeps one SQLite store on your machine. Tools read it over MCP, REST or a CLI, and one rule set is synced into CLAUDE.md, AGENTS.md, GEMINI.md, Cursor and Windsurf rules, and Copilot and Aider files.

Version 0.1.13 is a patch release. Here is what changed.

Start the MCP server from npm

aletheia mcp runs the MCP server over stdio. It is the same server as the aletheia-mcp command. With no checkout and no global install, an MCP client can start it like this:

{
  "mcpServers": {
    "aletheia": { "command": "npx", "args": ["-y", "aletheia-mem", "mcp"] }
  }
}

Bun 1.1 or newer must be on the PATH. bunx aletheia-mem mcp works too.

The MCP Registry entry starts the server

Aletheia is listed in the official MCP Registry as io.github.mohamed-ashraf-elsaed/aletheia-mem. A registry client runs an npm package by its name, so it ran npx aletheia-mem. That is the CLI, and with no argument it only printed its help. Up to 0.1.12, a registry install got the help text instead of a server.

The manifest now passes the package argument mcp, so the client runs npx aletheia-mem mcp. The published package answered initialize and listed its 13 tools through npx -y aletheia-mem@0.1.13 mcp. No registry client has installed it from the new entry yet, so that part is not tested.

A new docs layout

The docs site has a new layout: a sidebar of collapsible groups, an "On this page" column, and dark code blocks with a copy button. Every page has search (Ctrl K, Cmd K on a Mac, or /) and a light and dark theme switch. The pages still load no script file and nothing from another origin.

Install

npm install -g aletheia-mem
aletheia-server

It needs Bun 1.1 or newer. The server binds to loopback only. There is no account and no telemetry.

Status

Alpha. Hooks have run in real sessions of Claude Code, Command Code and Codex CLI, on one machine. Cursor, Gemini CLI and Windsurf configs are written from their docs and not yet tested on a real install.

If you run it with a tool I have not tested, open an issue with the tool, its version, the command and the result.

Aletheia 0.1.12: docs on their own site, release notes per version, MCP registry publishing

Mohamed Ashraf Elsaed — Mon, 02 Nov 2026 15:09:19 +0000

Version 0.1.12 is a patch release. Here is what changed.

The docs have their own address

The documentation moved from GitHub Pages to aletheia.mohamedashrafelsaed.com/docs. Paths are unchanged, and the old address redirects. Each version now has its own release notes page, and an Atom feed lists every release.

Published to the MCP registry on every tag

The release workflow bumps server.json to the tag and publishes it to the official MCP registry with the registry's mcp-publisher CLI and GitHub OIDC. 0.1.12 is listed there as io.github.mohamed-ashraf-elsaed/aletheia-mem.

Settings shows only what the code reads

The Settings page lists three settings: facts.minConfidence, context.facts and rules.reviewDays. Seven settings that nothing read are gone. Use environment variables for the provider, fact budgets and excluded projects. Redaction is always on.

Install

npm install -g aletheia-mem
aletheia-server

It needs Bun 1.1 or newer. The server binds to loopback only. There is no account and no telemetry.

Status

If you run it with a tool I have not tested, open an issue with the tool, its version, the command and the result.

Give all your AI coding tools one shared memory (free, local, 3 commands)

Mohamed Ashraf Elsaed — Tue, 27 Oct 2026 18:03:56 +0000

If you use more than one AI coding tool, you have probably noticed two things.

First, every tool forgets. Close the session and the decisions, the quirks of your codebase and the "never do it this way" rules are gone.

Second, every tool wants its own rules file: CLAUDE.md, AGENTS.md, Cursor rules, and so on. You end up copying the same rules into several places, and they drift apart.

I wanted one place for both. So I made Aletheia: a free, local memory and rules hub for AI coding tools.

What it does

Keeps memory in one SQLite database on your machine.
Lets any tool read it over MCP, REST or the command line.
Writes your rules once and syncs them into each tool's own instruction file.
Exports and imports, so you can move between tools.
Has a small local web app to search, edit, pin and review what was stored.

No account. No telemetry. It listens on 127.0.0.1 only.

Try it in three commands

You need Bun 1.1 or newer.

npm install -g aletheia-mem
aletheia-server
# open http://127.0.0.1:37790

That is the whole setup. There are no runtime dependencies to install.

Setting up a tool

Aletheia can write the config for the tools it knows. By default it only shows you what it would do:

aletheia install --list          # what it can set up, per tool
aletheia install claude-code     # dry run: prints every file it would change
aletheia install claude-code --write

Without --write nothing is written. With it, every changed file gets a timestamped backup first.

Two details I care about

Secrets stay out. Before anything is stored, capture hooks redact secrets and anything inside <private> blocks.

Memory is treated as untrusted. A stored note could contain text like "ignore your instructions". So when Aletheia hands memory back to a model, it wraps it in a marked block and tells the model it is data, not instructions. Tags inside notes are neutralised so a note cannot close the block early.

Honest status

It is alpha. The memory engine and the installers pass their tests. But I have not yet opened a real host app with a generated config, so I do not claim it "works with" any specific tool. I also measure retrieval, not answer accuracy, and I say so in the README.

I built it with Claude Code: agents did most of the implementation in separate git worktrees, one task per commit, and I wrote the specs, reviewed the results and decided what counted as done.

Help wanted

The most useful thing you can do is try it with the tool you use and tell me what happens. Open an issue with the tool, its version, the command you ran and what the tool did.

What would you want your tools to remember?

I am Mohamed Ashraf Elsaed, a technical lead in Cairo. Aletheia's page, with the docs and numbers: https://mohamedashrafelsaed.com/projects/aletheia/

Building AI Agents in Laravel with Claude Code SDK

Mohamed Ashraf Elsaed — Sun, 22 Feb 2026 18:59:20 +0000

I just released an open-source Laravel package that lets you build AI agents powered by Claude Code directly in your PHP applications.

The Problem

Claude Code is an incredibly powerful agent — it can read files, edit code, run bash commands, search the web, and delegate to subagents. But it's a CLI tool. If you want those capabilities inside a Laravel app (automated code reviews, AI-powered admin tools, agentic workflows), you need a programmatic interface.

The Solution

Claude Agent SDK for Laravel wraps the Claude Code CLI and gives you a fluent PHP API.

composer require mohamed-ashraf-elsaed/claude-agent-sdk-laravel

Quick Start

use ClaudeAgentSDK\Facades\ClaudeAgent;

$result = ClaudeAgent::query('What files are in this directory?');

echo $result->text();       // Final text result
echo $result->costUsd();    // Cost in USD
echo $result->sessionId;    // Session ID for resuming

Fluent Options Builder

use ClaudeAgentSDK\Options\ClaudeAgentOptions;

$options = ClaudeAgentOptions::make()
    ->tools(['Read', 'Edit', 'Bash', 'Grep', 'Glob'])
    ->permission('acceptEdits')
    ->maxTurns(10)
    ->model('claude-sonnet-4-5-20250929')
    ->cwd(base_path());

$result = ClaudeAgent::query('Find and fix the bug in auth.php', $options);

Real-Time Streaming

Perfect for broadcasting progress to your frontend via WebSockets:

$result = ClaudeAgent::streamCollect(
    prompt: 'Create a REST API for products',
    onMessage: function ($message) {
        if ($message instanceof AssistantMessage) {
            broadcast(new AgentProgress($message->text()));
        }
    },
);

Subagents

Define specialized agents that Claude delegates tasks to:

$options = ClaudeAgentOptions::make()
    ->tools(['Read', 'Grep', 'Task'])
    ->agent('security-reviewer', new AgentDefinition(
        description: 'Security code review specialist',
        prompt: 'Find vulnerabilities in PHP/Laravel code.',
        tools: ['Read', 'Grep', 'Glob'],
    ))
    ->agent('test-writer', new AgentDefinition(
        description: 'PHPUnit test writer',
        prompt: 'Write comprehensive PHPUnit tests.',
        tools: ['Read', 'Write', 'Bash'],
    ));

Structured Output

Get validated JSON matching a schema:

$options = ClaudeAgentOptions::make()
    ->outputFormat([
        'type' => 'object',
        'properties' => [
            'issues' => [
                'type' => 'array',
                'items' => [
                    'type' => 'object',
                    'properties' => [
                        'file' => ['type' => 'string'],
                        'severity' => ['type' => 'string'],
                        'message' => ['type' => 'string'],
                    ],
                ],
            ],
        ],
    ]);

$data = ClaudeAgent::query('Find TODOs in src/', $options)->structured();

Session Management

Continue conversations across requests:

$result1 = ClaudeAgent::query('Read the auth module');
$sessionId = $result1->sessionId;

// Later — resume with full context
$result2 = ClaudeAgent::query(
    'Now add email verification',
    ClaudeAgentOptions::make()->resume($sessionId),
);

MCP Server Integration

Connect external tools via Model Context Protocol:

use ClaudeAgentSDK\Tools\McpServerConfig;

$options = ClaudeAgentOptions::make()
    ->mcpServer('database', McpServerConfig::stdio(
        command: 'npx',
        args: ['@modelcontextprotocol/server-database'],
        env: ['DB_URL' => config('database.url')],
    ));

Full Feature List

Fluent options builder with IDE autocompletion
Streaming with real-time message processing
Subagent delegation
MCP server integration (stdio + SSE)
Structured output with JSON schema
Session resume and fork
Full message/content block parsing
Laravel service provider, facade, config publishing
PHP 8.1-8.4, Laravel 10/11/12
Full test suite

DEV Community: Mohamed Ashraf Elsaed

Aletheia 0.1.13: start the MCP server from npm, and a fix for the MCP Registry entry

Start the MCP server from npm

The MCP Registry entry starts the server

A new docs layout

Install

Status

Aletheia 0.1.12: docs on their own site, release notes per version, MCP registry publishing

The docs have their own address

Published to the MCP registry on every tag

Settings shows only what the code reads

Install

Status

Give all your AI coding tools one shared memory (free, local, 3 commands)

What it does

Try it in three commands

Setting up a tool

Two details I care about

Honest status

Help wanted

Building AI Agents in Laravel with Claude Code SDK

The Problem

The Solution

Quick Start

Fluent Options Builder

Real-Time Streaming

Subagents

Structured Output

Session Management

MCP Server Integration

Full Feature List

Links