# marketnow-memory

Persistent, local memory for **any** AI agent — one file, zero dependencies.

Works with Claude Code, Cursor, Codex CLI, Windsurf, Cline, Continue, Aider,
OpenCode, Goose, Amp and **any MCP-compatible client** (Model Context Protocol,
stdio JSON-RPC 2.0).

- **No cloud** — data stays in `~/.marketnow-memory/memory.json`
- **No npm install** — single file, Node >= 18, standard library only
- **No API keys** — search runs locally (TF-IDF cosine similarity + lexical fallback)
- **No telemetry** — zero network calls
- **Tested** — 29 integration checks (`node test.js`)

## Quick start

```bash
git clone https://github.com/alicelabs-llc/marketnow-memory.git
cd marketnow-memory
node test.js          # verify: 29 checks pass
node marketnow-memory.js status
node marketnow-memory.js add "We use pnpm, never npm" --type rule --topic tooling --importance 5
node marketnow-memory.js search "package rules"
node marketnow-memory.js profile
```

## Register with your agent

Add to your MCP client config (see `mcp-config.example.json` for Claude Code,
Cursor, Codex CLI, Windsurf, Cline, Continue, Aider, OpenCode, Goose, Amp):

```json
{
  "mcpServers": {
    "marketnow-memory": {
      "command": "node",
      "args": ["/absolute/path/to/marketnow-memory/marketnow-memory.js"]
    }
  }
}
```

Then ask your agent:

> what do you remember about me?

and it will call `memory_profile`.

## The 8 MCP tools

| Tool | What it does |
|------|--------------|
| `memory_bootstrap` | Session start: top rules/preferences + recent + optional query matches |
| `memory_search` | TF-IDF cosine similarity + lexical fallback, recency/importance boosts |
| `memory_add` | Store a decision / rule / preference / fact (importance 1-5, tags, topic) |
| `memory_profile` | Full profile grouped by topic |
| `memory_forget` | Remove by id or query (dry-run by default, `confirm:true` to delete) |
| `memory_clear` | Wipe everything (requires `confirm:true`) |
| `memory_status` | Health + storage info |
| `memory_export` | Full backup as JSON or Markdown |

## Memory model

```json
{
  "id": "mem-mu5vezi6-6654ad",
  "type": "rule",                     // decision | rule | preference | fact
  "topic": "tooling",
  "tags": ["pnpm", "package-manager"],
  "content": "We use pnpm, never npm",
  "importance": 5,
  "created_at": "2026-09-17T18:36:17.221Z"
}
```

## How search works (honest notes)

Local search = **TF-IDF vectors + cosine similarity** over content, topic and
tags, with small recency and importance boosts, plus a lexical substring
fallback when token overlap is zero. It needs **no API keys and runs offline**,
which is the point. The trade-off is honest: it is statistical recall, not
embedding-grade world knowledge — "package manager" will match "pnpm" only if
the memory text mentions it. Write memories with descriptive keywords and recall
stays sharp. If you need vector-database recall over millions of documents,
point a real vector DB at your data instead — this tool is the lightweight,
zero-dependency option.

## Storage & privacy

- Default: `~/.marketnow-memory/memory.json` (override: `MARKETNOW_MEMORY_HOME`)
- Atomic writes (`.tmp` + rename)
- Plain JSON — inspectable, portable, `memory_export`-able
- Never store credentials, tokens or private keys in agent memory

## Development

```bash
node test.js                          # integration test (spawns real server)
MARKETNOW_MEMORY_HOME=/tmp/mem node marketnow-memory.js add "x"   # isolated store
```

`marketnow-memory.js` exports its operations (`op_add`, `op_search`, …) for
programmatic use.

## License

MIT — (c) 2026 AliceLabs LLC. Part of [MarketNow](https://www.marketnow.site).