open-index/open-npm huggingface dataset:
npm package: @postnesia/cli
Description: Commander CLI for Postnesia — direct tool access for agents
Latest version: 0.1.22

# @postnesia/cli

Commander CLI for the Postnesia memory system. A like-for-like interface over the MCP tools for use when no MCP connection is available.

## Usage

```bash
npx postnesia <command> [options]
```

Requires `DATABASE_URL` and `GEMINI_API_KEY` in a `.env` file in your working directory, or set as environment variables.

## Commands

### Memory

```bash
postnesia memory search "<query>" [--limit N]
postnesia memory add "<content>" --type <type> --importance <1-5> --tags "<t1,t2>" [--content-l1 "<summary>"] [--context "<ctx>"] [--core]
postnesia memory update-core <id> --content "<content>" --content-l1 "<summary>"
postnesia memory recent [--hours N] [--limit N]
postnesia memory stats
postnesia memory consolidate
postnesia memory relationships <id>
```

**Memory types:** `event` `decision` `lesson` `preference` `person` `technical`

### Journal

```bash
postnesia journal add <YYYY-MM-DD> "<content>" [--learned "..."] [--key-moments "..."] [--mood "..."]
postnesia journal recent [--days N]
```

### Tasks

```bash
postnesia task create "<title>" [-d "<description>"] [-s <session-id>] [-m <memory-id>]
postnesia task update <id> [-s <status>] [-t "<title>"] [-d "<description>"]
postnesia task list [--status <status>] [--session-id <id>] [-l N]
```

**Task statuses:** `pending` `in_progress` `completed` `cancelled`

## Notes

- `memory search` uses Gemini vector embeddings — `GEMINI_API_KEY` is required
- `memory add` and `memory update-core` also embed content before writing
- Output is JSON for list/search commands; plain text for mutations
npm package: @postnesia/db
Description: AI Agent memory context database
Latest version: 0.1.22

# @postnesia/db

SQLite database layer for the Postnesia memory system. Provides schema migrations, Gemini embeddings, vector search, access tracking, and importance dynamics.

## Exports

```ts
import { getDb, queries, createMemory } from '@postnesia/db';
import { embed } from '@postnesia/db/embeddings';
import { logAccess } from '@postnesia/db/access';
import { runConsolidation } from '@postnesia/db/importance';
```

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `DATABASE_URL` | Yes | — | Absolute `file://` URL to the SQLite database |
| `GEMINI_API_KEY` | Yes | — | Google Gemini API key for embeddings |
| `EMBEDDING_MODEL` | No | `gemini-embedding-001` | Embedding model name |
| `EMBEDDING_DIMENSIONS` | No | `768` | Embedding vector dimensions |

`DATABASE_URL` must be an absolute path, e.g. `file:///home/user/workspace/memory.db`.

## Setup

### First-time (copies schema into your project and migrates)

```bash
npx postnesia-migrate-init
```

### Apply pending migrations

```bash
npx postnesia-migrate-dev
```

### Seed core memories

Seeds the operational guide into the database as a core memory:

```bash
npx postnesia-seed
```

## Bins

| Command | Description |
|---|---|
| `postnesia-migrate-init` | Copy `schema.prisma` to your project and run initial migration |
| `postnesia-migrate-dev` | Run `prisma migrate dev` against your database |
| `postnesia-seed` | Insert core bootstrap memories |

## Schema Overview

- `memory` — main memory records with `content`, `content_l1`, `type`, `importance`, `core`, timestamps
- `tag` / `memory_tag` — many-to-many tag associations
- `relationship` — directional links between memories
- `vec_memories` — sqlite-vec virtual table for vector similarity search
- `access_log` — read access history used by the importance system
- `journal` — daily journal entries
- `task` — task records with status and optional session grouping
npm package: @postnesia/hooks
Description: Session bootstrap hook — loads L1 memory context at startup
Latest version: 0.1.22

# @postnesia/hooks

Session bootstrap hook for Postnesia. Loads core memories and high-importance L1 summaries from the database and injects them into the agent's context at session start.

## How it works

At session start the hook queries the database for:
- All **core memories** (always loaded, never decay)
- **Working memory** — non-core memories with importance >= 3

Output is written to stdout in a structured block:

```
--- POSTNESIA MEMORY CONTEXT ---

[CORE MEMORIES]
#1 [technical] How Postnesia is used...

[WORKING MEMORY — L1 summaries, importance >= 3]
#4 [lesson] (imp:4) Learned that...

--- END MEMORY CONTEXT ---
```

Claude Code injects stdout from `SessionStart` hooks into the conversation, so the agent sees this context before the first user message.

If the database does not exist yet the hook exits silently (no error).

## Usage

### Claude Code (SessionStart hook)

Add to `.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx postnesia-claude"
          }
        ]
      }
    ]
  }
}
```

### Programmatic (handler export)

The `./handler` export provides a handler that can be wired into other agent frameworks. It populates the `BOOTSTRAP.md` bootstrap file slot with the formatted memory context:

```ts
import handler from '@postnesia/hooks/handler';
```

## Environment Variables

Inherits from `@postnesia/db` — requires `DATABASE_URL` to be set.
npm package: @postnesia/mcp
Description: An MCP server to interact with the Postnesia database
Latest version: 0.1.22

# @postnesia/mcp

MCP server for the Postnesia memory system. Exposes all memory, journal, and task operations as Model Context Protocol tools over stdio.

## Usage

Add to your MCP config (e.g. `.claude/settings.json` or Claude Desktop):

```json
{
  "mcpServers": {
    "postnesia": {
      "command": "npx",
      "args": ["postnesia-mcp"],
      "env": {
        "DATABASE_URL": "file:///absolute/path/to/memory.db",
        "GEMINI_API_KEY": "your-gemini-api-key",
        "EMBEDDING_MODEL": "gemini-embedding-001",
        "EMBEDDING_DIMENSIONS": "768"
      }
    }
  }
}
```

`DATABASE_URL` must be an absolute `file://` URL.

## Tools

### Memory

| Tool | Required | Optional |
|---|---|---|
| `memory_search` | `query` | `limit` (default: 10) |
| `memory_add` | `content`, `type`, `importance`, `tags` | `contentL1`, `context`, `core` |
| `memory_update_core` | `memoryId`, `content`, `contentL1` | — |
| `memory_recent` | — | `hours` (default: 24), `limit` (default: 20) |
| `memory_stats` | — | — |
| `memory_consolidate` | — | — |
| `memory_relationships` | `memoryId` | — |

**Memory types:** `event` `decision` `lesson` `preference` `person` `technical`

### Journal

| Tool | Required | Optional |
|---|---|---|
| `journal_add` | `date` (YYYY-MM-DD), `content` | `learned`, `keyMoments`, `mood` |
| `journal_recent` | — | `days` (default: 7) |

### Tasks

| Tool | Required | Optional |
|---|---|---|
| `task_create` | `title` | `description`, `session_id`, `memory_id` |
| `task_update` | `taskId` | `status`, `title`, `description` |
| `task_list` | — | `status`, `session_id`, `limit` (default: 50) |

**Task statuses:** `pending` `in_progress` `completed` `cancelled`

## Implementation

Built with `McpServer` from `@modelcontextprotocol/sdk` and Zod input schemas. All read operations (`memory_search`, `memory_recent`) automatically log accesses which feed into the importance decay/boost system.
npm package: @postnesia/mind
Description: D3.js force-directed graph visualization for Belle's memory database
Latest version: 0.1.22

# @postnesia/db

SQLite database layer for the Postnesia memory system. Provides schema migrations, Gemini embeddings, vector search, access tracking, and importance dynamics.

## Exports

```ts
import { getDb, queries, createMemory } from '@postnesia/db';
import { embed } from '@postnesia/db/embeddings';
import { logAccess } from '@postnesia/db/access';
import { runConsolidation } from '@postnesia/db/importance';
```

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `DATABASE_URL` | Yes | — | Absolute `file://` URL to the SQLite database |
| `GEMINI_API_KEY` | Yes | — | Google Gemini API key for embeddings |
| `EMBEDDING_MODEL` | No | `gemini-embedding-001` | Embedding model name |
| `EMBEDDING_DIMENSIONS` | No | `768` | Embedding vector dimensions |

`DATABASE_URL` must be an absolute path, e.g. `file:///home/user/workspace/memory.db`.

## Setup

### First-time (copies schema into your project and migrates)

```bash
npx postnesia-migrate-init
```

### Apply pending migrations

```bash
npx postnesia-migrate-dev
```

### Seed core memories

Seeds the operational guide into the database as a core memory:

```bash
npx postnesia-seed
```

## Bins

| Command | Description |
|---|---|
| `postnesia-migrate-init` | Copy `schema.prisma` to your project and run initial migration |
| `postnesia-migrate-dev` | Run `prisma migrate dev` against your database |
| `postnesia-seed` | Insert core bootstrap memories |

## Schema Overview

- `memory` — main memory records with `content`, `content_l1`, `type`, `importance`, `core`, timestamps
- `tag` / `memory_tag` — many-to-many tag associations
- `relationship` — directional links between memories
- `vec_memories` — sqlite-vec virtual table for vector similarity search
- `access_log` — read access history used by the importance system
- `journal` — daily journal entries
- `task` — task records with status and optional session grouping