memgc — Node.js bindings

Self-hostable agentic memory for production agents. Your agents remember things. Over time they remember too much, get confused, and cost a fortune. memgc throws away the old stuff intelligently — so your agents stay sharp, fast, and cheap. Runs on your own server.

This npm package is a thin Node.js wrapper around the memgc Python library. It spawns a Python subprocess and exchanges line-delimited JSON-RPC over stdin and stdout — no native binaries, no compilation, runs anywhere Python ≥ 3.12 is installed.

Install

# 1. Install the Python core (one-time, system-wide or per-user)
pip install memgc
# or:  uv add memgc

# 2. Install the Node bindings
npm install memgc

If python3 is not on your PATH as python3, set MEMGC_PYTHON=/path/to/your/python before importing.

Quickstart

const { MemGC } = require('memgc');

(async () => {
  const mc = await MemGC.open('./mydb');

  await mc.extract([
    { speaker: 'Alice', content: 'I moved to Lisbon in March 2024.', date: '2024-03-15' },
  ]);

  const ans = await mc.answer('Where does Alice live now?');
  console.log(ans.text);             // synthesized answer
  console.log(ans.memories.length);  // supporting evidence count

  await mc.close();
})();

API

All methods return Promises. The five primitives match the Python package exactly:

| Method | Returns | | --- | --- | | MemGC.open(path) | Promise<MemGC> | | mc.extract(messages, sessionDate?) | Promise<string[]> — ids of new memories | | mc.consolidate(messages) | Promise<string> — YAML AgentState snapshot | | mc.dreaming({ threshold?, half_life_days?, dry_run? }) | Promise<DreamStats> | | mc.answer(question, { k_pool?, n_iterations?, n_samples?, use_reranker?, verbose? }) | Promise<Answer> | | mc.close() | Promise<void> |

Answer is { text, memories[], elapsed_s, tokens: { input, output } }.

Configuration

LLM and embedder configuration lives in the Python process — set your provider keys via a .env file at the directory where you spawn Node, or via environment variables (AZURE_OPENAI_*, OPENAI_API_KEY, etc.). See the Python README for the full list.

Implementation notes

• One MemGC.open() call spawns one Python subprocess. The subprocess lives until close() (or the parent Node process exits).
• Concurrent calls on a single MemGC are serialized by Python — this matches the Python library's threading model. Open multiple instances for true parallelism.
• Set MEMGC_DEBUG=1 to forward the Python subprocess's stderr to your Node stderr.

License

MIT