Mnemovela-open

Open (Apache-2.0) client SDKs, examples, API reference, and prebuilt binaries
for Mnemovela.

What is Mnemovela?

Mnemovela is a cognition runtime that gives software agents long-term memory,
context assembly, and knowledge representation. Think of it as a memory
subsystem that sits alongside your LLM: every observation, fact, decision, and
plan is stored as a typed, temporal, branchable record, and you retrieve it with
a hybrid search (lexical + semantic + relation + time) plus context assembly.

Mnemovela's data model combines Git-like branching with cognitive memory types:

Every record is immutable and append-only, tagged with branch, timestamp,
retention tier, and identity scope (tenant/project). The engine owns the
semantics; storage backends are replaceable.

What is Mnemovela-open?

Mnemovela-open is the public, open-source window into Mnemovela. It contains
everything you need to integrate with a running Mnemovela server — client
libraries, CLI tools, protocol schemas, and API documentation —?under the
Apache-2.0 license. The Mnemovela engine source is not included here; this
repository ships only the client-facing layer.

What's in this repository:

What's NOT here (in the private Mnemovela engine repo):
the engine server + storage backends + advanced algorithms (LLM reranking,
LLM extraction, graph/neighborhood expansion, cloud connectors, contradiction
detection, simulation). Prebuilt binaries of the engine servers ARE available
from this repository's releases.

Getting started

1. Get a server binary. Download a prebuilt server binary from the latest
   GitHub release for your platform.
   (See local build if you prefer to build from the
   engine source.)

2. Start the server:

   mnemovela-http   # JSON-RPC over HTTP + REST, default 127.0.0.1:8080
   mnemovela-grpc   # gRPC, default :9090
   

   The server starts with an in-memory backend. Set Mnemovela_GO_PEBBLE_PATH for
   pebble persistence.

3. Pick a client and integrate:

   Python (gRPC + HTTP):

   pip install ./clients/python
   

   from mnemovela_client import MnemovelaClient  # gRPC
   from mnemovela_client import MnemovelaHttpClient  # HTTP (full method surface)
   client = MnemovelaHttpClient("http://127.0.0.1:8080")
   client.add_episode(branch_name="main", content="hello")
   client.search_memory(branch_name="main", query="hello")
   

   Go (gRPC + HTTP):

   import "github.com/axisvela/mnemovela-open/clients/go/mnemovela"
   t := mnemovela.NewJSONRPCTransport("http://localhost:8080")
   c := mnemovela.New(t)
   raw, _ := c.AddEpisode(ctx, mnemovela.P{"branch_name":"main","content":"hi"})
   

   TypeScript (HTTP):

   import { MnemeClient } from "@axisvela/mnemovela-client";
   const client = new MnemeClient("http://127.0.0.1:8080");
   await client.addEpisode({ branch_name: "main", content: "hello" });
   

   CLI:

   mnemovela --transport http add-episode --branch main --content "hi"
   mnemovela search --branch main --query "hi"
   

   See docs/api/ for the full API reference, and examples/ for runnable
   quickstarts.

How the clients talk to the server

All clients speak one of three protocols, all implemented by the same server
binary:

Adoption

Sustained consumers of the Mnemovela contract against this SDK surface (as of
2026-08-21, core v0.15.0):

• Web console — the Mnemovela Angular web app consumes mnemovela.rest.v1
  through clients-compatible REST endpoints; contract-level specs pin those
  endpoints and the live-backend e2e smoke exercises them on every push.
  Interface stayed churn-free across v0.13 → v0.15 (32 component/service
  specs green).
• Coding Agent Continuity pilot — examples/coding-agent-continuity/
  drives admission, context assembly, and revision against a live engine and
  keeps a regression test mirroring the flow.
• Quickstarts — examples/ exercise the Python, Go, and TypeScript clients
  against a running server.

These are first-party consumers; the open SDK 1.0 gate additionally requires a
stable-minor track record with sustained use (see the core
docs/status-and-roadmap.md § Path to 1.0).

License

Source content is Apache-2.0 (LICENSE). Prebuilt binaries are distributed
under separate terms (BINARY-LICENSE.md). The Mnemovela engine (not in this
repository) is licensed separately.

Building from source

The server binaries in the releases are built from the Mnemovela engine source. If
you have access to the engine repository, build them with:

cd go && CGO_ENABLED=0 go build ./cmd/mnemovela-http ./cmd/mnemovela-grpc ./cmd/mnemovela-jsonrpc-stdio ./cmd/mnemovela-mcp-stdio