---

Gnosion is a small, honest brain you can drop into anything: a product, a data pipeline, or your coding workflow. It holds several cognition domains (vision, text, design, tabular, memory) that each learn their own way, guards them so they never regress or memorise junk, and packs the whole thing into a single portable .gnosion file you can move between projects and machines.

It also doubles as a shared project memory for coding agents — Claude Code, Cursor, Windsurf, Cline, Aider, Zed, or your own scripts — via a CLI and an MCP server, so agents stop re-deriving your decisions, drifting from your structure, or repeating fixed bugs.

• 🪶 Zero required dependencies. Pure-Python core — installs and runs anywhere, no PyTorch, no build step.
• 📈 Gets smarter on every input. Each learn() improves the right domain; memory recalls from a single example.
• 📦 Portable. export() → one .gnosion. load() it anywhere. Ship it in git.
• 🔌 Fully flexible. Add your own domains and swap in your own embedder in a line.
• 🤝 Universal agent memory. One CLI + one MCP server, shared across every agent.
• 🫱 Honest. Lightweight ML (nearest-centroid + k-NN over embeddings) — no magic, no black box. Optional extras add real semantic quality.
• 🕸️ Visual & interactive. gns ui opens a drag/zoom/spin neuro-graph of everything the brain knows, with views for knowledge, projects, and chat — feed it, map a project, and export a handoff right from the browser. See the dashboard.
• 🍽️ Feeds on anything. gns feed learns from .md files, folders, or web pages (with optional crawl) into named knowledge domains (marketing, SEO, DevOps…).

How it works (one glance)

Every input is embedded to a vector, routed to the domain's head, and folded into one portable file. Nothing else to run.

flowchart LR
  IN["input<br/>text · image · numbers"] --> EMB["embedder<br/>hashing (0-dep) or fastembed (semantic)"]
  EMB --> H{"domain head"}
  H -->|classifier| C["nearest-centroid + optional logreg<br/>champion / challenger — never regresses"]
  H -->|memory| M["k-NN cosine recall<br/>learns from ONE example · reinforces on hit"]
  C --> F[("one .gnosion file<br/>portable · git-committable")]
  M --> F
  F -.load anywhere.-> IN

Install

pip install gnosion                 # Python, zero deps
pip install "gnosion[embed]"        # + fastembed (ONNX MiniLM/CLIP) → semantic quality
pip install "gnosion[ml]"           # + numpy / scikit-learn acceleration

npm i -g gnosion                    # Node wrapper (bundles the Python core; needs Python 3.9+)

Automatic quality upgrades — zero code changes. Install an extra and Gnosion just gets better on its own:

• gnosion[ml] → classifiers automatically use a calibrated logistic regression (falls back to nearest-centroid otherwise). The .gnosion stays plain JSON — the model is re-fit from the stored samples, never pickled.
• gnosion[embed] → embeddings become semantic (fastembed ONNX MiniLM/CLIP, no torch) so paraphrases and visually-similar images match. Opt out with GNOSION_NO_FASTEMBED=1. A brain records which embedder it used, so it reloads consistently.

Quickstart (Python)

from gnosion import Gnosion

bx = Gnosion()                                    # 5 default cognition domains

# classify — teach with labels, then predict
bx.learn("text", "how do I reset my password", label="account")
bx.learn("text", "what are your opening hours", label="hours")
bx.train("text")
bx.predict("text", "i forgot my password")       # {'label': 'account', 'confidence': 0.83}

# remember facts / conventions — memory learns from ONE example
bx.remember("design", "auth pattern",
            "Use a JWT in an httpOnly cookie; the refresh token rotates.")
bx.recall("design", "auth pattern")               # {'value': '...', 'similarity': 1.0}

# vision (image bytes) and tabular (feature vectors) work the same way
bx.learn("vision", open("leak.jpg", "rb").read(), label="plumbing")
bx.learn("tabular", [500000, 0.1, 4.0, 30], label="affordable")

# one portable file → import anywhere
bx.export("company.gnosion")
same_brain = Gnosion.load("company.gnosion")

The 5 default cognition domains ("neurons")

Domain	Head	Input	What it does
vision	classifier	image bytes	what kind of thing is in the picture
text	classifier	text	intent / category of a message
design	memory	text	system-design & structure conventions (recall)
tabular	classifier	list of numbers	outcome from numeric features
memory	memory	text	general knowledge recall (from 1 example)

flowchart TB
  G(("🧠 Gnosion")) --> V["vision<br/><i>classifier · image</i>"]
  G --> T["text<br/><i>classifier · text</i>"]
  G --> D["design<br/><i>memory · text</i>"]
  G --> B["tabular<br/><i>classifier · numbers</i>"]
  G --> M["memory<br/><i>memory · text</i>"]

Add your own: bx.add_domain("sentiment", head="classifier", modality="text").

Universal coding-agent memory 🤝

A full agent-memory model any agent can read and write — persisted to ./.gnosion/project.gnosion in the repo. It covers the standard agent-memory types:

Type	Holds
fact	world / semantic facts
entity	facts about the user / project / environment / team / domain
experience	episodic — "did X → got Y" events (experience tracking)
observation	raw things noticed in the environment
skill	procedural, user-addable how-to procedures the agent recalls & follows
decision · convention · structure · bug · preference	how / why you work

CLI (any agent can shell out to this):

gns note "The user prefers concise plain-text replies" --kind entity --subject user
gns note "We use JWT in an httpOnly cookie; refresh rotates" --kind decision
gns experience "used dedup reuse for repeat photos" --outcome "served stale label; now re-runs"
gns observe "the vision model classifies category only, not sub-category"
gns skill "deploy" --when "shipping a change" --how "git pull; docker compose up -d --build"
gns ask    "how do we do auth"        # recall relevant memories (any type)
gns skills                            # list learned skills
gns brief                             # session-start briefing (facts, decisions, skills)
gns mem                               # counts by type

MCP — one config, works across MCP-capable agents (Claude Code, Cursor, Windsurf, Cline, Zed, …). They all share the same repo .gnosion, so memory carries across agents and sessions:

{ "mcpServers": { "gnosion": { "command": "gns", "args": ["mcp"] } } }

Tools exposed: remember · recall · record_experience · observe · add_skill · recall_skill · briefing · stats. (Pure stdlib JSON-RPC over stdio — no SDK needed.)

Python:

from gnosion.agent import AgentMemory
mem = AgentMemory(root=".")
mem.about("user", "prefers concise plain-text answers")        # entity fact
mem.experience("tried X", outcome="failed because Y")           # episodic
mem.observe("CI is flaky on the payments module")               # observation
mem.add_skill("deploy", when_to_use="shipping a change",
              how="git pull; docker compose up -d --build")     # user-added skill
mem.recall_skill("how do I ship this")                           # -> the deploy skill
mem.recall("how do we do auth")                                  # across all types
print(mem.briefing())

Recall matches shared words out of the box (zero-dep). For semantic paraphrase recall, pip install "gnosion[embed]" and set GNOSION_SEMANTIC=1 (or AgentMemory(semantic=True)) — then it uses fastembed (ONNX MiniLM, no torch).

The walking brain 🚶

Gnosion is portable, so it goes with you. Every time an AgentMemory saves, it records the project into a global registry at ~/.gnosion/registry.json — so one brain remembers every project it has entered and what it learned in each. gns ui reads that registry to show the whole picture.

flowchart LR
  PA["project A<br/>.gnosion"] --> R
  PB["project B<br/>.gnosion"] --> R
  PC["project C<br/>.gnosion"] --> R
  R["~/.gnosion registry<br/><i>what learned where</i>"] --> UI["gns ui<br/>🕸️ neuro-graph"]

The interactive dashboard (gns ui)

gns ui                    # dashboard for THIS repo's ./.gnosion/project.gnosion
gns ui company.gnosion    # dashboard for any explicit .gnosion file
gns ui --port 9000        # pick a port (auto-finds a free one otherwise)

Opens a local, self-contained, interactive dashboard (pure stdlib server — no deps, no CDN, no internet). The main canvas is a live force-directed neuro-graph you can drag, zoom (scroll), pan (drag background), and spin (orbit toggle); double-click any neuron for details. The left rail switches views:

View	Shows
Neuro	every neuron the brain has learned — the whole mind, clustered by similarity (dot = neuron, edge = similarity, size = how often recalled)
Coding Agent	the project knowledge graph — files, functions, classes & concepts as typed nodes; imports/calls/references as edges; detected stack — with one-click handoff.md export
Chat / Training	the conversational brain (text · design · memory) + its clusters
<domain>	one nav per fed knowledge domain (marketing, seo, devops…) — appears automatically as the brain learns

Long lists are collapsed to the first 5 with a "see all N →" modal (searchable), so a big brain stays readable. The sidebar also lists every project the walking brain has entered (click to switch), and live stats. You can feed knowledge (paste text / a URL, optional crawl) and re-scan / export a handoff right from the toolbar.

flowchart LR
  subgraph UI["gns ui  ·  one canvas, many views"]
    N["🧠 Neuro<br/>all knowledge"]
    C["💻 Coding Agent<br/>files + imports + stack"]
    T["💬 Chat / Training<br/>text · design · memory"]
    K["📈 marketing / seo / devops…<br/>auto-appear per fed domain"]
  end
  BRAIN[(".gnosion")] --> UI
  UI -->|"+ Feed"| BRAIN
  C -->|"⬇ handoff.md"| AGENT["Claude · Codex · Cursor"]

Run gns ui locally to see it — the graph animates and is fully interactive. (The repo ships no PNGs; the diagram above is the layout.)

Feed it knowledge (gns feed)

Gnosion learns anything you point it at, into a named knowledge domain (which then becomes its own nav + cluster in the UI, and is searchable via gns ask). Pure stdlib.

gns feed notes.md --domain marketing              # a markdown/text file → chunked
gns feed ./kb --domain seo                         # a whole folder (.md/.txt/.rst)
gns feed https://site.com/post --domain dev        # one web page (HTML → text)
gns feed https://docs.x.io --crawl --depth 1 --max 20 --domain dev   # a small doc site
gns feed --text "SEO: titles drive CTR" --domain seo                  # a raw paste

Which source should I use?

Source	Best for	Notes
.md / .txt files ✅	curated knowledge you control	highest signal — chunked by heading/paragraph. Feed a whole folder at once.
A single URL	one research page / article	static HTML only (no JS rendering); tags stripped to text.
--crawl	a small doc site	follows same-host links up to --depth/--max, one request at a time.
--text	a quick paste	no file needed.

Chunks are matched by shared words by default. Install gnosion[embed] + GNOSION_SEMANTIC=1 for semantic recall (paraphrases match). This is how a domain like marketing, SEO, DevOps, or PyTorch recipes becomes a first-class part of the brain.

Map anything into a knowledge graph (gns mapping)

gns mapping turns a directory — a codebase, a docs folder, any tree of files — into a real knowledge graph the brain stores and traverses, so you can ask "what connects X to Y?" instead of grepping. (Inspired by Graphify, kept pure-Python, zero-dep, and general.)

gns mapping .                       # build / refresh the map for a directory
gns mapping query "auth database"   # a scoped subgraph around matching nodes
gns mapping path "login" "DatabasePool"   # shortest path between two things
gns mapping explain "UserService"   # a node + everything it connects to

The model — a graph you traverse, not embeddings:

	Kinds
Nodes	dir · file · function · class · module · route · concept (doc headings)
Edges	contains · defines · imports · inherits · calls · references

Each edge is tagged EXTRACTED (explicit in source) or INFERRED (resolved by analysis). Python is parsed with ast (functions, classes, methods, imports, calls, inheritance, routes); JS/TS via light regex; Markdown headings become concept nodes and [[wikilinks]] become references. The graph persists to .gnosion/graph.json (reusable, no re-parsing), and file/symbol notes also land in the brain's structure memory so gns ask still works.

$ gns mapping path "login" "DatabasePool"
{ "from": "login_route", "to": "DatabasePool",
  "path": ["login_route", "UserService.login", "DatabasePool"], "hops": 2 }

Because it's general, the same command maps a docs vault or a mixed folder — you get a graph of concepts and references, not just code.

Hand a project to a coding agent (gns handoff)

gns handoff -o PROJECT.md # ONE markdown: stack + file tree + per-file defs/routes/imports + memory briefing
gns handoff --as-claude   # write it as ./CLAUDE.md
gns handoff --as-agents   # write it as ./AGENTS.md

handoff turns the map — plus what the brain has learned about the project — into one file a coding agent reads instead of crawling every source file, saving tokens.

Two ways to plug it into an agent:

flowchart LR
  P["your project"] -->|gns mapping| B[(".gnosion<br/>graph.json")]
  B -->|gns handoff| MD["PROJECT.md / CLAUDE.md<br/><i>one-shot cheap context</i>"]
  B -->|gns mcp| MCP["MCP server<br/><i>live recall + traversal</i>"]
  MD --> A["Claude · Codex · Cursor"]
  MCP --> A

• Static — gns handoff → a single .md the agent loads once (cheap, offline).
• Live — the MCP server is the pluggable install: claude mcp add gnosion -- gns mcp; the agent then calls recall / briefing on demand across every session.

Use cases

One brain, many jobs — it is deliberately universal:

• Give a product its own brain — classify images/text on-device ($0, offline), learning from user confirmations; ship the trained brain as one file.
• A domain-expert brain — gns feed marketing, SEO, DevOps, legal, or product docs into named domains; the brain becomes a queryable expert you can commit and share.
• Coding-agent context — mapping + handoff hand any agent a whole project in one file (or a traversable graph); MCP gives it live recall. Less token burn, less drift.
• Agent memory across sessions & tools — capture decisions/conventions/bug-fixes once; every future agent session recalls them.
• An ML side-brain / pipeline component — use it inside a PyTorch or vision pipeline as a fast nearest-centroid classifier or a k-NN memory cache: log good predictions, recall them next time, or bootstrap labels before a heavy model is trained. Swap in your own embedder (.embed(x) -> vector) and it rides on your existing features.
• A learning layer over LLMs — remember the good answers an LLM gave; serve them locally next time (faster, cheaper, consistent).
• Edge / CPU classification — vision/text/tabular classifiers, no GPU, no framework.

Flexibility

• Custom domains: bx.add_domain(name, head="classifier"|"memory", modality="text"|"image"|"vector").
• Custom embedder: any object with .embed(x) -> list[float] and a stable .dim — plug in your own model, or pip install "gnosion[embed]" for fastembed.
• Custom heads: ClassifierHead / MemoryHead are plain classes with to_dict()/from_dict(); extend them and register in HEAD_TYPES.
• Portable format: the .gnosion is a zip (manifest.json + gzipped brain) — you can inspect, diff, or generate it yourself.

How it learns (and won't get worse)

• Classifier heads keep every labelled example and fit a per-label centroid over embeddings. train() carves a stable golden holdout, scores a challenger, and only promotes it if it doesn't regress — champion/challenger.
• Memory heads store (embedding → value) and answer by nearest-neighbour cosine above a confidence threshold — so paraphrases recall the right value and unrelated queries recall nothing (no confident-but-wrong answers).

API at a glance

Gnosion(dim=256, prefer_fastembed=False, domains=None)
  .learn(domain, x, label=None, value=None)   .remember(domain, cue, value)   .absorb(domain, q, a)
  .train(domain=None)   .predict(domain, x)   .recall(domain, q, min_sim=None)   .search(domain, q, k=5)
  .add_domain(name, head, modality)   .stats()   .export(path)   Gnosion.load(path)

CLI reference

gns note|ask|brief|mem                 # universal repo memory (./.gnosion/project.gnosion)
gns observe|experience|skill|skills    # episodic / procedural memory
gns feed <file|dir|url> --domain X     # teach new knowledge (--text, --crawl, --depth, --max)
gns mapping [path]                     # build a knowledge graph of a directory
gns mapping query|path|explain ...     # traverse it instead of grepping
gns handoff [--as-claude|--as-agents|-o F.md]   # export a single project map for coding agents
gns ui [file.gnosion] [--port N]       # 🕸️ interactive dashboard (local, 0-dep)
gns mcp                                # run the MCP server (stdio) for agents
gns learn|train|predict|recall <file.gnosion> <domain> <text> [--label/--value]
gns inspect|stats <file.gnosion>        # peek / full stats

Expand & scale it bigger

Gnosion is small on purpose, so growth is just composition:

• More brainpower per domain — install gnosion[embed] for semantic embeddings and gnosion[ml] for calibrated logistic-regression classifiers. Zero code changes; the .gnosion stays plain JSON (models are re-fit from stored samples, never pickled).
• More domains — bx.add_domain(name, head, modality) or just gns feed --domain new. Every domain is independent, so the brain scales sideways without retraining others.
• Bigger embedder — point a domain at any model exposing .embed(x) -> list[float] and a stable .dim (OpenAI embeddings, your own CLIP, a fine-tuned encoder). The graph, recall, and champion/challenger guard all keep working.
• Many brains, one mind — keep a per-repo .gnosion (committed) and let the ~/.gnosion registry aggregate them; gns ui shows all projects and lets you switch.
• Custom heads — subclass ClassifierHead / MemoryHead (they're plain to_dict()/from_dict() classes) and register in HEAD_TYPES for new learning rules.
• Sharding — split by domain into separate .gnosion files and load the one you need; each file is a self-contained zip you can diff, cache, or generate.

What Gnosion is — and isn't

It is a practical, portable, always-improving memory + classifier you can embed anywhere. It is not a replacement for a large language model, and importing a .gnosion will not magically make an LLM bug-free — it augments by remembering what worked and classifying what it has seen, so systems drift less and repeat fewer mistakes.

Learn more

• USAGE.md — a full how-to: install → app brain → project memory → coding agents (MCP) → AI agents → embedding in a system → Node/JS → sharing a brain.
• PUBLISHING.md — the exact GitHub / PyPI / npm steps.

MIT © Crave Asia / IPG