npm package: @morsa/memory-bank-local
Description: Local Memory Bank runtime and MCP host for coding agents.
Latest version: 0.1.5

# @morsa/memory-bank-local

`@morsa/memory-bank-local` is a local, cross-agent Memory Bank for coding agents.

It gives you one durable place for reusable rules and skills across:

- different agent providers
- different projects
- repeated sessions in the same project

The goal is simple:

- improve agent quality over time
- reduce repeated prompting and repeated context reconstruction
- save tokens by keeping stable guidance in a managed local memory layer

## Quick Start

Install globally:

```bash
npm install -g @morsa/memory-bank-local
```

Initialize once:

```bash
mb init
```

That is the whole manual setup.

After that, your agent can work with the Memory Bank during normal coding sessions. When a project has no bank yet, the agent can detect that and guide creation as part of the workflow.

## Why It Exists

Agent guidance is usually fragmented.

- Some rules live in `AGENTS.md`.
- Some live in `.cursor`, `.claude`, or `.codex`.
- Some are project-specific.
- Some should be shared across many repositories.
- Most provider-native flows are still weak at generating a good long-lived bank from real project evidence.

`@morsa/memory-bank-local` solves that by giving the agent one canonical local Memory Bank it can use across providers and across projects.

It is designed for two kinds of memory:

- cross-agent reusable guidance shared between projects
- project-specific guidance derived from the actual codebase and stack

## Supported Providers

Current provider integrations:

- Codex
- Cursor
- Claude Code

## What Happens Next

After `mb init`, the normal flow is intentionally lightweight:

1. You open a project in your agent.
2. The agent resolves Memory Bank context for that project.
3. If a project bank does not exist yet, the agent can propose creating it.
4. The agent can then keep using, improving, syncing, and editing the bank over time.

In practice, the agent can:

- create a project bank
- review and improve an existing bank
- sync an outdated bank layout
- add or update rules
- add or update skills
- delete obsolete entries
- read and inspect existing bank content

The goal is that the agent handles the workflow, instead of you manually managing rule files all the time.

## Why This Is Better Than Provider-Native Rules

Provider-native repository guidance is useful, but usually limited.

Common problems:

- guidance is locked to one provider
- project memory is hard to reuse across repositories
- generated rule sets often collapse into folder-structure summaries instead of real operational guidance
- stack-specific guidance is usually shallow and repetitive

`@morsa/memory-bank-local` aims to build better project memory by:

- separating shared and project-specific guidance
- deriving rules from real project evidence
- carrying reusable rules across repositories
- keeping one user-managed canonical layer that works with multiple agents

## Stats

Use `mb stats` for a local overview of the Memory Bank and recent activity:

```bash
mb stats
mb stats --project /absolute/project/path
mb stats --json
```

It currently shows:

- shared rule and skill counts
- project bank counts and creation states
- recent audit events
- tool and provider activity breakdowns

This is the first visibility layer; it will keep getting richer.

## What We Plan To Improve

Near-term product direction:

- better visualization of rules and skills
- richer stats, including token-oriented usage and cost insight
- stronger project-bank management workflows
- team and workspace-oriented memory sharing

The long-term direction is not just “local rule files”, but a real memory layer for agent work across projects, providers, and eventually teams.

## Current Notes

- `mb init` requires an interactive terminal
- at least one supported provider CLI must already be installed and available on `PATH`
- the local Memory Bank lives under `~/.memory-bank`