cogmemai-mcp

<p align="center">
  <img src="assets/hero.png" alt="CogmemAi — Cognitive Memory for Any Ai System" width="800">
</p>

[![npm version](https://img.shields.io/npm/v/cogmemai-mcp)](https://www.npmjs.com/package/cogmemai-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Quantum Safe](https://img.shields.io/badge/🛡%EF%B8%8F_Quantum-Safe-02ffba?style=flat&labelColor=1a1a2e)](https://hifriendbot.com/developer/)

# CogmemAi: A Thinking, Live Memory for Everything Ai

**It remembers what matters, enforces the rules you set before anything happens, and checks what your Ai did against what you asked. For assistants, agents, robots, vehicles and code.**

<p align="center">
  <img src="assets/demo.svg" alt="CogmemAi demo — your Ai assistant remembers your project across sessions" width="800">
</p>

CogmemAi is a portable memory layer that gives any Ai system persistent recall across sessions, devices, users, and teams — and captures knowledge autonomously, even when your Ai forgets to save. **95.10% accuracy on LongMemEval — top published score on the field's hardest long-term memory benchmark.** 91% on LoCoMo, above human performance (87.9%). Quantum-safe encryption. Works with Claude Code, Cursor, Windsurf, Cline, Continue, and any MCP-compatible tool. Switch editors, switch models, switch machines — your knowledge stays. Not just one score on a test — the most complete Ai memory system available.

## What's New in v3

### Guard and Review for Everything, Not Only Code (v3.28.0)

Until now the guard judged shell commands and the intent review judged code diffs, because those were the hooks a coding tool gave us. v3.28.0 opens both to any Ai through two tools and two REST endpoints:

- `guard_check`: "may I do this?" Any action (a message about to be sent, a purchase, a change, a command) is judged against the rules this person has asked their Ai to keep, plus the NEVER and MUST lines of the project intent. A literal check runs on every tier; the judged check on the paid tiers. Returns allow, ask or deny with the rule that applies, and fails open.
- `review_work`: "did I do what was asked?" Pass a description, output, message or transcript of what was done and it is reviewed against the intent document, or against an intent passed inline. Same plain-English result as the code review: summary, covered, uncovered, violations, coverage.

A support assistant, a companion, a robot's task planner and a coding agent now share one memory that shapes what any model does: it remembers, it enforces, it reviews. The same calls are on the SDKs (`guardCheck` / `reviewWork`, `guard_check` / `review_work`) and on REST as `POST /cogmemai/guard-check` and `POST /cogmemai/intent-check` with a `work` field.

### CogmemAi Intent: You Read the Intent, Not the Code (v3.26.0)

Spec files that live in a repository are per-repo, per-tool, and they rot. v3.26.0 adds one plain-English intent document per project that lives with you instead: what the project is for, what must always hold, what was decided and why, and what is out of scope. Write it with `set_intent`, read it with `get_intent`. Every session loads it right after the rules, every replacement is versioned, and it follows you into every tool that talks to CogmemAi.

Then it does two things a spec file cannot. The sentences under **Invariants** are compiled into the same enforceable patterns as rule memories, so `NEVER run \`pkill -u www lsphp\`` in your intent denies that command before it runs, with no network call. And at the end of every turn the changes are judged against the document on the CogmemAi server and reported in plain English for someone who does not read code: what changed, whether the intent covers it, what conflicts with it, and what the intent does not mention yet. A covered change earns silence. `COGMEMAI_INTENT_VERBOSE=1` shows the summary on every judged turn. Every check is logged to `~/.cogmemai/intent-log.jsonl`, so precision is measured rather than assumed.

The judged check runs on the paid tiers; the free tier still gets the enforced invariants and every deterministic review. See [Intent](#intent) below.

### CogmemAi Guard: Your Memory Now Stops Your Ai From Repeating Mistakes (v3.24.0)

Memory that only advises is memory your Ai can ignore under pressure. v3.24.0 adds a guard that turns what your project remembers into enforcement.

A PreToolUse hook judges every shell command before it runs. Six built-in rules cover the operations with no good unattended use: rewriting a whole crontab from a pipeline, destructive SQL against a live database, recursive deletes outside temp and build paths, force-pushing to a shared branch, piping a download into a shell, and killing shared server workers by name. The same rules are applied to what a command carries inside `ssh host "..."`, `bash -c "..."`, and a heredoc fed to a shell, because that payload runs on the far side exactly as written.

Then the part only a memory layer can do. Rule memories you save with `save_rule` become enforceable patterns. Write `NEVER run \`pkill -u www lsphp\`` in a rule and the next session denies that command, over ssh too, with the rule's own words as the reason. No code to edit. Add a `GUARD: <regex>` line to a rule for an exact pattern, or `GUARD: off` to keep a rule advisory.

A Stop hook reviews what actually changed at the end of each turn: credentials pasted into tracked source, version strings that disagree across release files, deleted files, large net deletions, a function now defined in two places, and remembered gotchas about the files that were touched. It reports; it never edits.

Every verdict is logged locally with secrets redacted, so precision is measured rather than assumed. Denials name the deliberate path forward, usually "run it yourself". The guard fails open on any error, and git remains the real undo. See [Guard](#guard) below.

v3.25.0 extends it past Claude Code: `guard shell-install` hooks every `bash -c` and `zsh -c` on the machine through `BASH_ENV`, so Cursor, Codex, Gemini CLI, and plain scripts get the same guard, the same remembered rules, and the same log.

### Loud Failures on Firewall Blocks (v3.20.0)

When a request to the CogmemAi backend is intercepted by an upstream firewall, CDN, or proxy, the response is HTML, not JSON. Earlier versions tried to JSON-parse it and threw a confusing `Unexpected token '<'` error, then silently retried the same blocked payload. v3.20.0 detects HTML responses, names the blocking layer when it can (NinjaFirewall, Cloudflare, ModSecurity), and surfaces a clear actionable error. Retryable 4xx responses with HTML bodies no longer trigger retry loops. The class of incident that can silently drop memory writes is now loud.

### Autonomous Memory — Your Ai Doesn't Decide Whether to Save Anymore (v3.15)

Every memory system has the same hidden failure mode: **the Ai has to choose to save, and under pressure it doesn't.** You can bake instructions into system prompts. You can nudge. But when your Ai is head-down on a coding task, it forgets to save — and the decisions you made two hours ago vanish when the context compacts.

CogmemAi v3.15 moves the decision out of the Ai's hands entirely. Your coding sessions are captured at the infrastructure level — decisions, file changes, bug fixes, and deployments land in memory without a single prompt. At session end, an intelligence pass distills them into structured memories: the right types, the right importance scores, the right scopes. Your Ai never sees this happen.

The result: a day of heavy coding produces 15–20 quality memories instead of 3. Future sessions pick up seamlessly. Your Ai stops re-litigating architectural choices you already made. **Stop reminding your Ai to remember. It just does.**

### Proactive Memory Recall (v3.12)

CogmemAi now **thinks before it speaks**. Before your Ai assistant suggests any action, approach, or recommendation, CogmemAi checks its memory first — automatically, on every topic.

- **`preflight` tool** — A fast, lightweight recall designed to be called before every suggestion. Your assistant checks what it already knows about a topic before opening its mouth. "Let's try approach X" → first checks if X was already tried, rejected, or completed. Sub-200ms, near-zero cost.
- **Prior context surfacing** — Every time a memory is saved, CogmemAi automatically searches for related prior memories across all topics — people, companies, technical approaches, features, everything — and surfaces them in the response. Your assistant never suggests something redundant.
- **Smart recall hooks** — In Claude Code, CogmemAi reads every user message and automatically injects relevant memories before the assistant responds. No manual recall needed — context arrives before the assistant starts thinking.
- **Upgraded recall engine** — Higher-dimensional semantic understanding, balanced reranking, keyword-expanded search, dual-path memory storage for more reliable retrieval, and adaptive search that expands automatically when initial results are low confidence.

The result: your Ai assistant stops suggesting things you've already tried, people you've already contacted, and approaches you've already rejected. Your brain is no longer the safety net for what your tools should already know.

### Wisdom Engine — Auto-Extracted Principles (v3.10)

CogmemAi now automatically detects patterns across your memories and extracts **factual principles**. While skills tell your Ai HOW to behave ("always use Zustand"), principles tell it what's TRUE about your project ("this codebase never validates inputs at service boundaries"). Principles are extracted from clusters of 5+ related memories, scored by confidence, and injected into every session. Use `extract_principles` to trigger manually or let it happen automatically.

### Remote MCP — Zero Install (v3.9)

CogmemAi now supports **Streamable HTTP transport** —