@hilbras/remembra 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to Remembra will be documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.0] — 2026-09-23
+
+### Added
+- Initial release: MCP memory server for AI assistants.
+- Four memory types: `fact`, `decision`, `role`, `history`.
+- Hybrid scopes: `global` + per-project isolation (no cross-project leaks).
+- File-based storage (`~/.remembra`, markdown + frontmatter), override via `REMEMBRA_HOME`.
+- Layered retrieval: roles always surface → scope → importance → recency → keywords.
+- MCP tools: `memory_store`, `memory_search`, `memory_list`, `memory_forget`.
+- Client setup docs for OpenCode, Claude Code, Cline, and Kimi Code.
+- Test suite (store round-trip, scope isolation, role priority, ranking, delete).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hilbras
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# Remembra 🧠
+
+**External memory for AI assistants.** Remembra stores facts, decisions, roles, and history
+outside the context window, and hands back only what's relevant — so your AI stops forgetting
+when the conversation gets long.
+
+[![npm](https://img.shields.io/npm/v/%40hilbras/remembra.svg)](https://www.npmjs.com/package/@hilbras/remembra)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-compatible-brightgreen.svg)](https://modelcontextprotocol.io)
+
+One memory server, many clients:
+
+| Client | Connection |
+|--------|-----------|
+| OpenCode | MCP (stdio) |
+| Claude Code | MCP (stdio) |
+| Cline | MCP (stdio) |
+| Kimi Code | MCP (stdio) |
+| ChatGPT | HTTP API + Custom GPT action *(v1.5)* |
+
+## The problem
+
+Every AI assistant has a context window. Fill it, and the model starts forgetting earlier
+decisions, repeating questions, and losing track of roles and preferences. Remembra moves
+long-term memory **out of the window and into storage**, then injects only the relevant
+subset each session.
+
+## How it works
+
+```
+Conversation ──► memory_store ──► ~/.remembra/ (markdown files)
+                                        │
+New session ──► memory_search ◄─────────┘ ──► relevant subset injected
+```
+
+Every memory has a **type**, a **scope**, tags, and an importance score:
+
+- **fact** — stable knowledge ("Project uses PostgreSQL 16")
+- **decision** — choices already made ("Chose JWT over sessions")
+- **role** — standing instructions ("Answer concisely"; *always* injected)
+- **history** — condensed chronology of past work
+
+**Scopes:**
+- `global` — relevant everywhere (preferences, roles)
+- any project path/id — only loaded when working in that scope, never leaks into other projects
+
+**Retrieval ranking:** roles always surface → scope match → importance → recency → keyword overlap.
+
+## Quick start
+
+```bash
+npm install -g @hilbras/remembra
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add remembra -- remembra
+```
+
+**OpenCode** (`~/.config/opencode/opencode.json`):
+
+```json
+{
+  "mcp": {
+    "remembra": {
+      "type": "local",
+      "command": ["remembra"]
+    }
+  }
+}
+```
+
+More clients (Cline, Kimi Code) in **[docs/clients.md](docs/clients.md)**.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `memory_store` | Save a fact / decision / role / history |
+| `memory_search` | Retrieve relevant memories (pass `scope` = current project) |
+| `memory_list` | Browse stored memories |
+| `memory_forget` | Delete by id |
+
+Full reference: **[docs/tools.md](docs/tools.md)**
+
+## Documentation
+
+| Doc | What's inside |
+|-----|--------------|
+| [Memory model](docs/memory-model.md) | Types, scopes, ranking, storage format |
+| [Tool reference](docs/tools.md) | Every MCP tool with arguments |
+| [Client setup](docs/clients.md) | Config for each supported tool |
+| [Contributing](CONTRIBUTING.md) | Dev workflow and guidelines |
+| [Changelog](CHANGELOG.md) | Release history |
+
+## Storage
+
+Memories live as readable markdown files you can inspect, edit, and version:
+
+```
+~/.remembra/
+├── global/            # always-relevant memories
+└── scopes/
+    └── <project>/     # project-scoped memories
+```
+
+Override the location with `REMEMBRA_HOME`.
+
+## Development
+
+```bash
+git clone https://github.com/Hilbras/Remembra.git
+cd Remembra
+npm install
+npm run build   # compile
+npm test        # run tests
+```
+
+## Roadmap
+
+- **v1** *(current)* — MCP server for coding tools, file storage, layered retrieval
+- **v1.5** — HTTP API + ChatGPT Custom GPT action
+- **v2** — automatic session-digest extraction, embeddings behind `memory_search`
+- **v3** — SQLite for scale, duplicate merging, memory decay
+
+## License
+
+[MIT](LICENSE) © Hilbras

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { MemoryStore } from "./store.js";
+import { search } from "./retrieval.js";
+import { StoreInput } from "./types.js";
+const store = new MemoryStore(MemoryStore.defaultRoot());
+const server = new McpServer({ name: "remembra", version: "0.1.0" });
+server.registerTool("memory_store", {
+    title: "Store a memory",
+    description: "Persist a fact, decision, role or history entry so it survives context window resets. " +
+        "Use type 'fact' for stable knowledge, 'decision' for choices already made, " +
+        "'role' for standing instructions/roles, 'history' for condensed chronology of past work.",
+    inputSchema: {
+        type: z.enum(["fact", "decision", "role", "history"]),
+        content: z.string().describe("The memory itself, written as a standalone statement"),
+        scope: z
+            .string()
+            .optional()
+            .describe("'global' for always-relevant memories, or a project path/id for project-scoped ones"),
+        tags: z.array(z.string()).optional(),
+        importance: z.number().int().min(1).max(5).optional().describe("1=minor, 5=critical (default 3)"),
+        source: z.string().optional().describe("Originating session or client"),
+    },
+}, async ({ type, content, scope, tags, importance, source }) => {
+    const memory = await store.store(StoreInput.parse({ type, content, scope, tags, importance, source }));
+    return { content: [{ type: "text", text: `Stored ${memory.type} memory ${memory.id} (scope: ${memory.scope})` }] };
+});
+server.registerTool("memory_search", {
+    title: "Search memories",
+    description: "Retrieve relevant memories from external storage. Call this at the start of a session " +
+        "(or whenever prior context might exist) to recover facts, decisions, roles and history.",
+    inputSchema: {
+        query: z.string().optional().describe("Keywords to match (omit to get a scope/recency-ranked list)"),
+        scope: z.string().optional().describe("Current project path or workspace id to filter by"),
+        type: z.enum(["fact", "decision", "role", "history"]).optional(),
+        limit: z.number().int().min(1).max(50).optional(),
+    },
+}, async ({ query, scope, type, limit }) => {
+    const results = search(await store.all(), { query, scope, type, limit });
+    const text = results.length === 0
+        ? "No matching memories."
+        : results
+            .map((m) => `[${m.id}] ${m.type.toUpperCase()} (scope: ${m.scope}, importance: ${m.importance}, ${m.updatedAt.slice(0, 10)})\n${m.content}`)
+            .join("\n\n");
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("memory_list", {
+    title: "List memories",
+    description: "List stored memories, optionally filtered by scope or type.",
+    inputSchema: {
+        scope: z.string().optional(),
+        type: z.enum(["fact", "decision", "role", "history"]).optional(),
+    },
+}, async ({ scope, type }) => {
+    let memories = await store.all();
+    if (scope)
+        memories = memories.filter((m) => m.scope === scope || m.scope === "global");
+    if (type)
+        memories = memories.filter((m) => m.type === type);
+    memories.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    const text = memories.length === 0
+        ? "No memories stored yet."
+        : memories.map((m) => `[${m.id}] ${m.type} (${m.scope}): ${m.content.split("\n")[0]}`).join("\n");
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("memory_forget", {
+    title: "Delete a memory",
+    description: "Permanently delete a memory by its id.",
+    inputSchema: { id: z.string() },
+}, async ({ id }) => {
+    const ok = await store.forget(id);
+    return {
+        content: [{ type: "text", text: ok ? `Deleted memory ${id}.` : `No memory with id ${id}.` }],
+        isError: !ok,
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`Remembra memory server running (root: ${MemoryStore.defaultRoot()})`);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/retrieval.d.ts

@@ -0,0 +1,10 @@
+import { Memory, SearchQuery } from "./types.js";
+/**
+ * Layered retrieval (decision from Q4):
+ *   1. Roles always pass (they are instructions).
+ *   2. Scope match (global + current scope beat other scopes).
+ *   3. Importance, recency, and keyword overlap contribute to the score.
+ *
+ * Embeddings can replace the keyword part later without changing callers.
+ */
+export declare function search(memories: Memory[], q: SearchQuery): Memory[];

package/dist/retrieval.js

@@ -0,0 +1,51 @@
+/**
+ * Layered retrieval (decision from Q4):
+ *   1. Roles always pass (they are instructions).
+ *   2. Scope match (global + current scope beat other scopes).
+ *   3. Importance, recency, and keyword overlap contribute to the score.
+ *
+ * Embeddings can replace the keyword part later without changing callers.
+ */
+export function search(memories, q) {
+    const now = Date.now();
+    const terms = (q.query ?? "")
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((t) => t.length > 1);
+    const scored = memories
+        .filter((m) => (q.type ? m.type === q.type : true))
+        .map((m) => ({ m, score: score(m, terms, q.scope, now) }))
+        .filter(({ m, score }) => m.type === "role" || score > 0)
+        .sort((a, b) => b.score - a.score || b.m.updatedAt.localeCompare(a.m.updatedAt));
+    return scored.slice(0, q.limit ?? 10).map(({ m }) => m);
+}
+function score(m, terms, scope, now) {
+    let s = 0;
+    if (m.type === "role")
+        s += 1000;
+    if (m.scope === "global")
+        s += 100;
+    if (scope && m.scope === scope)
+        s += 150;
+    if (scope && m.scope !== scope && m.scope !== "global")
+        return 0; // other projects' memories don't leak in
+    s += m.importance * 10;
+    // Recency: half-life of ~30 days.
+    const ageDays = (now - Date.parse(m.updatedAt)) / 86_400_000;
+    if (!Number.isNaN(ageDays))
+        s += Math.max(0, 20 - ageDays / 3);
+    // Keyword overlap over content + tags.
+    if (terms.length > 0) {
+        const hay = (m.content + " " + m.tags.join(" ")).toLowerCase();
+        let hits = 0;
+        for (const t of terms)
+            if (hay.includes(t))
+                hits++;
+        s += (hits / terms.length) * 60;
+    }
+    else {
+        s += 10; // no query: everything eligible scores a little
+    }
+    return s;
+}
+//# sourceMappingURL=retrieval.js.map

package/dist/retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval.js","sourceRoot":"","sources":["../src/retrieval.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,23 @@
+import { Memory, StoreInput } from "./types.js";
+/**
+ * File-based memory store.
+ *
+ * Layout (default root: ~/.remembra):
+ *   global/<id>.md            — memories valid everywhere
+ *   scopes/<scope>/<id>.md    — memories scoped to a project/workspace
+ *
+ * Each file is markdown with YAML-ish frontmatter for human readability
+ * and simple greppability.
+ */
+export declare class MemoryStore {
+    private readonly root;
+    constructor(root: string);
+    static defaultRoot(): string;
+    private fileFor;
+    store(input: StoreInput): Promise<Memory>;
+    forget(id: string): Promise<boolean>;
+    /** Load every memory across all scopes (global + scoped). */
+    all(): Promise<Memory[]>;
+    get(id: string): Promise<Memory | null>;
+    private findFile;
+}

package/dist/store.js

@@ -0,0 +1,143 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+/**
+ * File-based memory store.
+ *
+ * Layout (default root: ~/.remembra):
+ *   global/<id>.md            — memories valid everywhere
+ *   scopes/<scope>/<id>.md    — memories scoped to a project/workspace
+ *
+ * Each file is markdown with YAML-ish frontmatter for human readability
+ * and simple greppability.
+ */
+export class MemoryStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    static defaultRoot() {
+        return process.env.REMEMBRA_HOME ?? path.join(os.homedir(), ".remembra");
+    }
+    fileFor(m) {
+        if (m.scope === "global") {
+            return path.join(this.root, "global", `${m.id}.md`);
+        }
+        const safeScope = m.scope.replace(/[^a-zA-Z0-9._/-]/g, "_");
+        return path.join(this.root, "scopes", safeScope, `${m.id}.md`);
+    }
+    async store(input) {
+        const now = new Date().toISOString();
+        const memory = {
+            id: randomUUID().slice(0, 8),
+            type: input.type,
+            content: input.content,
+            scope: input.scope,
+            tags: input.tags,
+            importance: input.importance,
+            createdAt: now,
+            updatedAt: now,
+            source: input.source,
+        };
+        const file = this.fileFor(memory);
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, render(memory), "utf8");
+        return memory;
+    }
+    async forget(id) {
+        const file = await this.findFile(id);
+        if (!file)
+            return false;
+        await fs.unlink(file);
+        return true;
+    }
+    /** Load every memory across all scopes (global + scoped). */
+    async all() {
+        const files = [];
+        for (const dir of [path.join(this.root, "global"), path.join(this.root, "scopes")]) {
+            files.push(...(await walk(dir)));
+        }
+        const memories = await Promise.all(files.map((f) => parse(f)));
+        return memories.filter((m) => m !== null);
+    }
+    async get(id) {
+        const file = await this.findFile(id);
+        if (!file)
+            return null;
+        return parse(file);
+    }
+    async findFile(id) {
+        const files = await walk(path.join(this.root, "global"), path.join(this.root, "scopes"));
+        return files.find((f) => path.basename(f, ".md") === id) ?? null;
+    }
+}
+async function walk(...dirs) {
+    const out = [];
+    for (const dir of dirs) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory())
+                out.push(...(await walk(full)));
+            else if (e.name.endsWith(".md"))
+                out.push(full);
+        }
+    }
+    return out;
+}
+function render(m) {
+    const lines = [
+        "---",
+        `id: ${m.id}`,
+        `type: ${m.type}`,
+        `scope: ${m.scope}`,
+        `tags: [${m.tags.join(", ")}]`,
+        `importance: ${m.importance}`,
+        `created: ${m.createdAt}`,
+        `updated: ${m.updatedAt}`,
+        m.source ? `source: ${m.source}` : undefined,
+        "---",
+        "",
+        m.content,
+        "",
+    ];
+    return lines.filter((l) => l !== undefined).join("\n");
+}
+async function parse(file) {
+    try {
+        const raw = await fs.readFile(file, "utf8");
+        const match = raw.match(/^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/);
+        if (!match)
+            return null;
+        const meta = {};
+        for (const line of match[1].split("\n")) {
+            const idx = line.indexOf(":");
+            if (idx === -1)
+                continue;
+            meta[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+        }
+        const tagsRaw = (meta.tags ?? "[]").replace(/^\[|\]$/g, "");
+        return {
+            id: meta.id ?? path.basename(file, ".md"),
+            type: (meta.type ?? "fact"),
+            content: match[2].trim(),
+            scope: meta.scope ?? "global",
+            tags: tagsRaw ? tagsRaw.split(",").map((t) => t.trim()) : [],
+            importance: Number(meta.importance ?? 3),
+            createdAt: meta.created ?? new Date(0).toISOString(),
+            updatedAt: meta.updated ?? meta.created ?? new Date(0).toISOString(),
+            source: meta.source,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+/** The four memory types Remembra stores. */
+export declare const MemoryType: z.ZodEnum<["fact", "decision", "role", "history"]>;
+export type MemoryType = z.infer<typeof MemoryType>;
+/**
+ * Scope of a memory.
+ * - "global": always relevant (user preferences, roles, general facts)
+ * - any other string: project/workspace scope (e.g. a repo path or project id)
+ */
+export type MemoryScope = string;
+export interface Memory {
+    id: string;
+    type: MemoryType;
+    content: string;
+    scope: MemoryScope;
+    tags: string[];
+    importance: number;
+    createdAt: string;
+    updatedAt: string;
+    source?: string;
+}
+export declare const StoreInput: z.ZodObject<{
+    type: z.ZodEnum<["fact", "decision", "role", "history"]>;
+    content: z.ZodString;
+    scope: z.ZodDefault<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    importance: z.ZodDefault<z.ZodNumber>;
+    source: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "fact" | "decision" | "role" | "history";
+    content: string;
+    scope: string;
+    tags: string[];
+    importance: number;
+    source?: string | undefined;
+}, {
+    type: "fact" | "decision" | "role" | "history";
+    content: string;
+    scope?: string | undefined;
+    tags?: string[] | undefined;
+    importance?: number | undefined;
+    source?: string | undefined;
+}>;
+export type StoreInput = z.infer<typeof StoreInput>;
+export interface SearchQuery {
+    query?: string;
+    scope?: string;
+    type?: MemoryType;
+    limit?: number;
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+/** The four memory types Remembra stores. */
+export const MemoryType = z.enum(["fact", "decision", "role", "history"]);
+export const StoreInput = z.object({
+    type: MemoryType,
+    content: z.string().min(1),
+    scope: z.string().default("global"),
+    tags: z.array(z.string()).default([]),
+    importance: z.number().int().min(1).max(5).default(3),
+    source: z.string().optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,6CAA6C;AAC7C,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAsB1E,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACrD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC"}

package/docs/clients.md

@@ -0,0 +1,90 @@
+# Client Setup
+
+Remembra speaks MCP over stdio — one server process, any compatible client.
+
+> Replace `/home/gin/work/Hilbras/Memory` with wherever you installed Remembra,
+> or use the global install: `npx @hilbras/remembra`.
+
+## OpenCode
+
+Add to `~/.config/opencode/opencode.json` (global) or a project's `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "remembra": {
+      "type": "local",
+      "command": ["node", "/home/gin/work/Hilbras/Memory/dist/index.js"]
+    }
+  }
+}
+```
+
+## Claude Code
+
+```bash
+claude mcp add remembra -- node /home/gin/work/Hilbras/Memory/dist/index.js
+```
+
+Or in `.mcp.json` (project) / `~/.claude.json` (user):
+
+```json
+{
+  "mcpServers": {
+    "remembra": {
+      "command": "node",
+      "args": ["/home/gin/work/Hilbras/Memory/dist/index.js"]
+    }
+  }
+}
+```
+
+## Cline
+
+Cline settings → MCP Servers → Add:
+
+```json
+{
+  "mcpServers": {
+    "remembra": {
+      "command": "node",
+      "args": ["/home/gin/work/Hilbras/Memory/dist/index.js"]
+    }
+  }
+}
+```
+
+## Kimi Code
+
+Add to the MCP config file used by Kimi CLI:
+
+```json
+{
+  "mcpServers": {
+    "remembra": {
+      "command": "node",
+      "args": ["/home/gin/work/Hilbras/Memory/dist/index.js"]
+    }
+  }
+}
+```
+
+## ChatGPT
+
+*Planned for v1.5* — an HTTP layer exposing the same handlers, wired to a
+Custom GPT action with API-key auth.
+
+## Environment
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `REMEMBRA_HOME` | `~/.remembra` | Where memory files live |
+
+## Tips
+
+- **Pass `scope`** — every client should give Remembra its current project path when
+  calling `memory_search`, so project memories don't mix across repos.
+- **Roles are always injected** — put standing instructions in `type: "role"` and they'll
+  never be filtered out by ranking.
+- **One server, shared brain** — all clients write to the same storage, so a decision made
+  in Claude Code is visible in OpenCode.

package/docs/memory-model.md

@@ -0,0 +1,114 @@
+# The Memory Model
+
+Remembra stores four kinds of memories. Every memory you save carries one of these types,
+and the type controls how it's used at retrieval time.
+
+## Types
+
+### `fact`
+Stable knowledge about the world, a project, or the user.
+
+```
+type: fact
+content: The API rate limit is 100 requests/minute.
+content: User prefers concise answers without filler.
+```
+
+### `decision`
+Choices that have already been made — so they don't get re-litigated every session.
+
+```
+type: decision
+content: Chose PostgreSQL over MongoDB for the events table (decided 2026-09-20).
+```
+
+### `role`
+Standing instructions and roles. **Roles always surface in search results** — they are
+treated as instructions, not suggestions.
+
+```
+type: role
+content: You are the architect. Never modify test files without asking.
+```
+
+### `history`
+Condensed chronology of what already happened — a lean summary instead of a raw transcript.
+
+```
+type: history
+content: Phase 1: built the auth API, hit a token refresh bug, resolved by rotating keys.
+```
+
+## Scopes
+
+Every memory belongs to exactly one scope:
+
+| Scope | Meaning | Injected when |
+|-------|---------|---------------|
+| `global` | Relevant everywhere (preferences, roles, general facts) | Any session |
+| `<project path or id>` | Belongs to one project/workspace | Only sessions in that scope |
+
+Scope isolation is strict: memories scoped to `/repo/a` are **never** returned to a session
+in `/repo/b`. Global memories are always visible.
+
+```json
+{ "type": "decision", "content": "...", "scope": "/home/gin/work/Hilbras/Memory" }
+```
+
+## Metadata
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `type` | `fact \| decision \| role \| history` | required |
+| `content` | string | required — written as a standalone statement |
+| `scope` | string | defaults to `global` |
+| `tags` | string[] | boosts keyword matching |
+| `importance` | 1–5 | defaults to 3; higher ranks higher |
+| `source` | string | originating session/client (optional) |
+| `id` | 8-char id | assigned automatically |
+| `createdAt` / `updatedAt` | ISO timestamps | assigned automatically |
+
+## Retrieval ranking
+
+When `memory_search` runs, memories are scored in layers:
+
+1. **Roles always pass** (+1000) — instructions never get filtered out.
+2. **Scope gate** — other projects' memories are excluded entirely;
+   the current scope scores highest (+150), `global` always passes (+100).
+3. **Importance** — up to +50 for importance 5.
+4. **Recency** — decays over roughly a 30-day half-life (up to +20).
+5. **Keyword overlap** — up to +60 based on the fraction of query terms matched
+   in content and tags.
+
+Embeddings are planned for v2 and will slot in behind the same `memory_search`
+interface without changing any client.
+
+## Storage format
+
+Memories are plain markdown files with frontmatter — greppable, editable by hand,
+git-friendly:
+
+```markdown
+---
+id: 7133edba
+type: decision
+scope: global
+tags: [architecture]
+importance: 4
+created: 2026-09-23T02:51:41.999Z
+updated: 2026-09-23T02:51:41.999Z
+---
+
+Chose file-based storage for v1
+```
+
+Layout:
+
+```
+$REMEMBRA_HOME/            # defaults to ~/.remembra
+├── global/
+│   └── <id>.md
+└── scopes/
+    └── <scope>/
+        └── <id>.md
+```

package/docs/tools.md

@@ -0,0 +1,75 @@
+# Tool Reference
+
+Remembra exposes four MCP tools. All of them work the same way across every
+MCP-compatible client.
+
+## `memory_store`
+
+Persist a memory so it survives context-window resets.
+
+| Argument | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `type` | `fact \| decision \| role \| history` | ✅ | — | What kind of memory this is |
+| `content` | string | ✅ | — | The memory, written as a standalone statement |
+| `scope` | string | no | `global` | `global`, or a project path/id |
+| `tags` | string[] | no | `[]` | Keywords that boost retrieval |
+| `importance` | 1–5 | no | `3` | Ranking weight |
+| `source` | string | no | — | Originating session/client |
+
+**When to use which type:**
+- Something the model should *know* → `fact`
+- Something already *decided* → `decision`
+- A standing *instruction* or persona → `role`
+- A summary of *what happened* → `history`
+
+Returns the assigned memory id.
+
+## `memory_search`
+
+Retrieve relevant memories. Call at the **start of a session** (to recover prior context)
+and whenever earlier work might be referenced.
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `query` | string | no | Keywords; omit for a scope/recency-ranked list |
+| `scope` | string | no | Current project path/id — pass it whenever you have one |
+| `type` | memory type | no | Restrict to one type |
+| `limit` | 1–50 | no | Max results (default 10) |
+
+Returns formatted memories:
+
+```
+[7133edba] DECISION (scope: global, importance: 4, 2026-09-23)
+Chose file-based storage for v1
+```
+
+## `memory_list`
+
+Browse what's stored — useful for auditing or showing the user their memory.
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `scope` | string | no | Filter by scope (includes `global`) |
+| `type` | memory type | no | Filter by type |
+
+Returns one line per memory, newest first.
+
+## `memory_forget`
+
+Permanently delete a memory.
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | ✅ | Memory id (from `memory_store` or `memory_list`) |
+
+Returns an error result if no memory matches the id.
+
+---
+
+## Suggested session flow
+
+```
+1. memory_search { scope: <current project> }     → recover roles, facts, decisions
+2. ... work happens; model calls memory_store when something worth keeping emerges ...
+3. (v2) automatic session digest sweeps anything missed
+```

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@hilbras/remembra",
+  "version": "0.1.0",
+  "description": "External memory for AI assistants — remember facts, decisions, roles and history across sessions. MCP server for OpenCode, Claude Code, Cline, Kimi Code and more.",
+  "type": "module",
+  "bin": {
+    "remembra": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/test",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "node --test \"dist/test/*.test.js\"",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hilbras/Remembra.git"
+  },
+  "homepage": "https://github.com/Hilbras/Remembra#readme",
+  "bugs": {
+    "url": "https://github.com/Hilbras/Remembra/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "ai",
+    "assistant",
+    "context",
+    "external-memory",
+    "long-term-memory",
+    "llm",
+    "opencode",
+    "claude-code",
+    "cline"
+  ],
+  "author": "Hilbras",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.0"
+  }
+}